1. 项目概述：为什么 Plone 5 主题开发需要 Grunt 加速？

Plone 5 的主题开发，本质上是一场“前端工程化”与“CMS 约束环境”的持续博弈。你刚在 Plone 5.2 环境里搭好一个新站点，准备给客户做一个响应式主题——结果发现，每次改一行 CSS，就得手动执行bin/buildout、重启bin/instance fg、清浏览器缓存、再刷新页面……整个流程耗时 90 秒起步。更糟的是，你写的 SCSS 文件一旦嵌套层级深了点，plone.app.theming自带的编译器就报错，连错误行号都不给你；JS 模块用 RequireJS 写着写着，依赖链一乱，控制台满屏undefined is not a function；而当你终于把图标字体生成好了，又发现++resource++mytheme/fonts/路径下文件没更新——因为 Plone 的资源注册机制根本没感知到你本地磁盘上的变更。这不是效率问题，这是开发节奏被反复打断后的认知损耗。Speed Up Your Plone 5 Theming with Grunt这个标题，说的不是“加个工具图新鲜”，而是直指 Plone 5 主题开发者每天真实遭遇的三大硬伤：编译不可控、资源不同步、反馈不即时。Grunt 在这里不是万能胶，而是你和 Plone 后端之间的一条专用数据通道——它把 SCSS 编译、JS 合并压缩、SVG 转图标字体、静态资源自动同步、甚至浏览器自动刷新这些动作，全部从 Plone 的 Python 进程里剥离出来，交给 Node.js 前端工具链独立运行。这意味着你改完src/scss/main.scss，3 秒内浏览器就刷新出效果；你新增一个src/js/modules/carousel.js，Grunt 自动把它塞进main.js并注入 RequireJS 配置；你拖进一张src/icons/arrow-right.svg，Grunt 就生成新的字体文件、CSS 声明、HTML 示例页，全在build/目录下备好。它不改变 Plone 的任何架构，但彻底重构了你的工作流节奏。适合谁？不是只写 HTML 的美工，也不是纯后端的 Zope 开发者，而是那些既要懂portal_css注册逻辑、又要手写 Flexbox 布局、还得调试require(['jquery'], function($) {...})的 Plone 全栈主题工程师。如果你还在用 Sublime Text + 手动刷新 + 心算路径拼写来推进项目，这篇就是为你写的实战手册。

2. 整体设计思路与方案选型逻辑

2.1 为什么是 Grunt，而不是 Gulp、Webpack 或直接用 Plone 自带工具？

这个问题我踩过三次坑才理清楚。第一次用 Gulp，写了一堆gulp.watch()监听任务，结果发现 Gulp 4 的异步流在 Windows 上和 Plone 的collective.plonetruegallery插件冲突，gulp.src('src/**/*')会漏掉某些.less文件；第二次试 Webpack 5，配置了webpack-dev-server和html-webpack-plugin，本想热替换模板，但 Plone 的theme.html是通过plone.app.theming的 XSLT 引擎解析的，Webpack 根本无法介入其 DOM 构建流程，最后只能退回到静态 HTML 预览模式，完全脱离 Plone 环境；第三次干脆放弃前端构建工具，直接用 Plone 自带的plone.app.theming的lessc编译器，结果在@import 'variables';时，它死活找不到src/less/variables.less，查源码才发现它只认portal_resources下的路径，根本不支持相对路径导入。Grunt 成为最终选择，核心在于它的确定性和可拆解性。Grunt 的任务是原子化的：grunt-contrib-sass只管编译，grunt-contrib-requirejs只管打包，grunt-sync只管复制文件，每个插件职责单一、文档清晰、错误提示明确。更重要的是，Grunt 的watch任务可以精确到文件类型和路径深度——比如watch: { scss: { files: ['src/scss/**/*.scss'], tasks: ['sass:dev'] } }，它不会误触发 JS 任务，也不会因为node_modules目录太大而卡死。而 Plone 5.2 的 Python 环境（通常基于 Python 2.7 或 3.6）对 Node.js 版本并不敏感，Grunt CLI 1.5.3 完全兼容 Node.js 14.x，这比 Webpack 5 要求 Node.js 12+ 更宽松。最关键的是，Grunt 的grunt-plone插件生态虽小，但足够精准：grunt-plone-themeresource能直接读取registry.xml里的资源声明，自动映射++resource++mytheme/css/main.css到build/css/main.css，省去了手动维护路径的麻烦。这不是技术先进性的选择，而是在 Plone 5 的现实约束下，最不容易翻车的务实方案。

2.2 整体架构：三层隔离 + 单向同步

整个加速体系不是把所有东西塞进一个 Gruntfile，而是按职责划分为三个逻辑层：

• 源码层（src/）：存放所有人类可读、可编辑的原始文件。包括src/scss/（SCSS 源码）、src/js/（ES5 模块化 JS）、src/icons/（SVG 图标）、src/images/（原始 PNG/JPG）、src/templates/（用于预览的静态 HTML）。这一层严禁出现任何编译产物，Git 忽略build/和node_modules/。

• 构建层（build/）：Grunt 的输出目录，完全由自动化任务生成。包含build/css/main.css（已压缩的 CSS）、build/js/main.min.js（合并压缩的 JS）、build/fonts/（图标字体文件）、build/preview/（静态预览页）。这个目录的内容，必须能被 Plone 直接识别——即build/css/main.css对应++resource++mytheme/css/main.css，路径结构严格一致。

• 部署层（profiles/default/registry.xml）：Plone 的资源注册中心。这里不放文件，只放声明。例如<record name="plone.resources/mytheme-css"><value><dict><element key="js">++resource++mytheme/js/main.min.js</element><element key="css">++resource++mytheme/css/main.css</element></dict></value></record>。Grunt 不修改此文件，但grunt-plone-themeresource会读取它，确保build/下的文件路径与注册路径完全匹配。

三者关系是单向的：src/→（Grunt 编译）→build/→（Plone 启动时加载）→ 浏览器渲染。没有反向操作，不搞“实时热重载注入 Plone 进程”，因为那会破坏 Plone 的 ZODB 事务一致性。这种设计牺牲了“毫秒级刷新”的幻觉，换来了100% 可复现、可回滚、可审计的构建结果——上线前你只要对比build/和profiles/default/的哈希值，就能确认生产环境和本地构建完全一致。

2.3 关键决策：为什么放弃 LiveReload，坚持 BrowserSync？

Plone 社区早期流行用grunt-contrib-livereload，原理是在页面插入一段 JS 脚本，监听 Grunt 的 WebSocket 信号。但我在实际项目中发现两个致命问题：第一，Plone 的portal_message提示框、#content-core的 AJAX 加载、以及plone.app.contenttypes的富文本编辑器，都会动态修改 DOM，导致 LiveReload 的 DOM 替换逻辑失效，经常出现“样式刷了但内容没变”或“JS 重载后事件绑定丢失”；第二，当 Plone 启用plone.app.caching时，livereload.js本身会被 Varnish 或 Nginx 缓存，导致新版本脚本加载失败。BrowserSync 则完全不同：它启动一个独立的代理服务器（默认http://localhost:3000），把所有请求转发给 Plone（如http://localhost:8080），同时注入自己的脚本。关键在于，它不替换 DOM，而是强制整个页面 reload，且 reload 前会清空浏览器缓存（通过添加时间戳参数?t=1678886400123）。实测下来，BrowserSync 在 Plone 5.2 + Firefox 102 环境下，从保存文件到页面完全刷新完成，稳定在 2.3~2.7 秒之间，误差小于 0.2 秒。而且它自带 UI 控制台（http://localhost:3001），能看到所有设备连接状态、文件变更日志、网络请求瀑布图——当客户说“你们的按钮在 iPad 上点不了”，我直接打开控制台，切到 iPad 模拟视图，点一下按钮，立刻看到touchstart事件是否触发，比在真机上盲调快 5 倍。这不是炫技，是把不可见的交互问题，变成可见的调试数据。

3. 核心细节解析与实操要点

3.1 目录结构标准化：为什么src/必须严格分层？

Plone 主题的目录混乱是效率杀手。我见过最离谱的案例：一个主题包里，css/目录下混着main.css（手写）、bootstrap.css（CDN 下载）、custom.less（半成品）、print.css（从未启用）；js/目录里有jquery.min.js（v1.12）、jquery-3.6.0.min.js（新版）、carousel.js（ES6 语法）、legacy.js（IE8 兼容补丁）。Grunt 无法智能判断哪些该编译、哪些该忽略、哪些该压缩。因此，src/目录必须遵循以下铁律：

• src/scss/：只放.scss文件，且禁止出现@import "bootstrap.css"这类非法语句。所有第三方 CSS 必须转为 SCSS（如bootstrap.scss）或通过npm install bootstrap后用@import "~bootstrap/scss/functions";引入。原因：grunt-contrib-sass只识别 SCSS 语法，.css文件会被跳过。

• src/js/：只放 ES5 兼容的.js文件（避免const、箭头函数），每个文件必须是一个 RequireJS 模块，格式为define(['jquery'], function($) { return { init: function() { ... } }; });。禁止出现全局变量var myPlugin = {...}。原因：grunt-contrib-requirejs打包时，会分析define()依赖树，自动生成main.js的模块定义，如果混入非模块化代码，打包后会报Uncaught Error: Mismatched anonymous define()。

• src/icons/：只放.svg文件，且每个 SVG 必须是单色、无渐变、无滤镜。命名规则：icon-arrow-right.svg、icon-user.svg。禁止出现icon-arrow-right@2x.svg或icon-user-blue.svg。原因：grunt-webfont工具在生成字体时，会把文件名icon-xxx转为 CSS 类名.icon-xxx，如果命名不规范，生成的类名会乱码或重复。

• src/templates/：放index.html（主预览页）、components/（独立组件 HTML，如button.html、card.html），所有路径引用必须相对src/templates/，例如<link rel="stylesheet" href="../build/css/main.css">。原因：BrowserSync 代理时，src/templates/是根目录，这样预览页才能正确加载构建产物。

提示：执行grunt init任务（需自定义）可一键生成标准src/结构，并写入.gitignore规则。我把它做成脚本，新项目创建后 3 秒内就准备好干净的起点。

3.2 SCSS 编译配置：如何让 Plone 主题真正“响应式”？

Plone 5 默认的plone.app.theming使用lessc，但 Less 对嵌套和循环支持弱，写媒体查询极其痛苦。SCSS 是唯一选择，但配置不当会引发灾难。关键参数如下（Gruntfile.js中）：

sass: { options: { implementation: require('sass'), // 必须用 Dart Sass，Node Sass 已废弃 sourceMap: true, // 生成 .css.map，Chrome DevTools 可直接定位到 .scss 行 outputStyle: 'compressed', // 生产环境用 compressed，开发用 'expanded' includePaths: [ 'node_modules/bootstrap/scss', 'node_modules/font-awesome/scss' ] }, dev: { files: { 'build/css/main.css': 'src/scss/main.scss' } } }

重点解释includePaths：Plone 主题常需复用 Bootstrap 组件，但不能直接@import "bootstrap/scss/bootstrap";，因为grunt-contrib-sass默认只搜索src/scss/下的路径。includePaths把node_modules/加入搜索队列，这样src/scss/main.scss里写@import "bootstrap/scss/functions";就能成功。实测发现，如果includePaths里路径写错（如少个s），Sass 编译会静默失败，build/css/main.css文件大小为 0 字节，但 Grunt 不报错。我的解决方案是加一道校验任务：

shell: { checkCssSize: { command: 'if [ ! -s build/css/main.css ]; then echo "ERROR: main.css is empty! Check sass includePaths."; exit 1; fi' } }

然后在watch任务中，把sass:dev和shell:checkCssSize串起来：tasks: ['sass:dev', 'shell:checkCssSize']。这样，只要编译出错，终端立刻红字报错，而不是等你刷新页面才发现白屏。

3.3 RequireJS 打包：如何让 Plone 的 JS 模块不打架？

Plone 5 的 JS 加载机制是双轨制：一部分是portal_javascripts里注册的全局脚本（如jquery.js），另一部分是主题里通过require(['jquery'], ...)按需加载的模块。Grunt 必须尊重这个规则。grunt-contrib-requirejs的配置核心是paths和shim：

requirejs: { compile: { options: { baseUrl: 'src/js', mainConfigFile: 'src/js/config.js', // RequireJS 配置文件 paths: { 'jquery': 'https://cdn.jsdelivr.net/npm/jquery@3.6.0/dist/jquery.min.js', 'bootstrap': 'https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js' }, shim: { 'bootstrap': { deps: ['jquery'], exports: '$.fn.modal' // 确保 bootstrap 加载后，$.fn.modal 存在 } }, name: 'main', // 入口模块名，对应 src/js/main.js out: 'build/js/main.min.js', optimize: 'uglify2' // 压缩引擎 } } }

这里的关键陷阱是paths的 CDN 地址。Plone 默认禁用外链（<script>标签被过滤），所以paths里写 CDN 是给 Grunt 打包用的，不是给浏览器运行时用的。实际部署时，build/js/main.min.js里已经把 jQuery 和 Bootstrap 的代码都合并进去了，paths只影响打包过程。而shim的作用是解决非 AMD 模块的依赖问题——Bootstrap 5 的bootstrap.bundle.min.js是 UMD 格式，shim告诉 RequireJS：“加载 bootstrap 前，必须先加载 jquery，且加载完成后，检查$.fn.modal是否存在，否则报错”。实测中，如果shim.exports写错（如写成'$.modal'），打包会成功，但运行时报TypeError: $(...).modal is not a function，排查起来极难。我的经验是：对每个第三方库，先在 Chrome Console 里手动执行define(['jquery', 'bootstrap'], function($, bs) { console.log($.fn.modal); });，确认返回函数后再写shim.exports。

3.4 图标字体生成：为什么 SVG 必须“扁平化”？

grunt-webfont是生成图标字体的主力，但它对 SVG 的要求苛刻。我曾用 Sketch 导出的 SVG，里面包含<g id="Layer_1">、<style>.cls-1{fill:#000;}</style>、<defs>等复杂结构，结果grunt-webfont生成的字体文件里，图标全是方块。根源在于：WebFont 工具只识别最简 SVG——单个<path>或<symbol>，且fill必须是内联属性，不能是 CSS 类。解决方案是预处理：用grunt-svgmin在生成字体前压缩 SVG。

svgmin: { options: { plugins: [ { removeViewBox: false }, // 必须保留 viewBox，否则图标尺寸错乱 { removeUselessStrokeAndFill: true }, { convertColors: { currentColor: true } }, // 把 fill="#000" 转为 fill="currentColor" { cleanupIDs: true } // 清理无用 ID，避免字体命名冲突 ] }, dist: { files: [{ expand: true, cwd: 'src/icons/', src: ['*.svg'], dest: 'src/icons-cleaned/', ext: '.svg' }] } }, webfont: { icons: { src: 'src/icons-cleaned/*.svg', dest: 'build/fonts/', options: { font: 'mytheme-icons', template: 'src/webfont/template.css', htmlDemo: true, normalize: true, fontHeight: 1001, // 必须设为奇数，避免字体基线偏移 round: 10e12 // 高精度坐标，防止锯齿 } } }

convertColors: { currentColor: true }是灵魂设置。它把所有fill="#000"转为fill="currentColor"，这样生成的 CSS 类.icon-user { color: #007bff; }就能控制图标颜色，而不用为每个图标写单独的 fill 规则。fontHeight: 1001是经验值：Plone 5 的plone.app.layout默认字体行高是 1.5，如果fontHeight设为 1000，图标在<span class="icon-user"></span>里会上浮 1px，和文字不对齐。实测 1001 最稳。

4. 实操过程与核心环节实现

4.1 初始化：5 分钟搭建可运行的 Grunt 环境

这不是“npm init → npm install grunt --save-dev”就完事的。Plone 主题的初始化必须一步到位，避免后续填坑。以下是我在 12 个项目中验证过的标准流程：

第一步：创建主题骨架

cd /path/to/plone/src/mytheme mkdir -p src/{scss,js,icons,images,templates} mkdir -p build/{css,js,fonts,preview} touch Gruntfile.js package.json

第二步：安装核心依赖（注意版本锁定）

npm init -y npm install --save-dev \ grunt@1.5.3 \ grunt-contrib-sass@2.0.0 \ grunt-contrib-requirejs@1.0.2 \ grunt-contrib-watch@1.1.0 \ grunt-browser-sync@2.3.0 \ grunt-webfont@1.10.0 \ grunt-svgmin@5.0.0 \ grunt-shell@3.0.1 \ grunt-plone-themeresource@0.2.0 \ sass@1.58.3

注意：grunt-plone-themeresource@0.2.0是专为 Plone 5.2 适配的版本，更高版本会因 Plone 的Products.CMFCoreAPI 变更而报错。

第三步：编写package.json的scripts

{ "scripts": { "dev": "grunt watch", "build": "grunt build", "init": "grunt init" } }

"dev"是日常开发命令，"build"用于 CI/CD 打包，"init"是初始化任务（见下文）。

第四步：定义Gruntfile.js的init任务

grunt.registerTask('init', 'Initialize theme structure', function() { grunt.file.write('src/scss/_variables.scss', '$primary: #007bff;\n$font-size-base: 1rem;'); grunt.file.write('src/scss/main.scss', '@import "variables";\nbody { font-size: $font-size-base; }'); grunt.file.write('src/js/config.js', 'require.config({ paths: { jquery: "//code.jquery.com/jquery-3.6.0.min.js" } });'); grunt.file.write('src/js/main.js', 'define(["jquery"], function($) { console.log("Theme JS loaded"); });'); grunt.file.write('src/templates/index.html', '<!DOCTYPE html><html><head><link rel="stylesheet" href="../build/css/main.css"></head><body><h1>MyTheme Preview</h1><script src="../build/js/main.min.js"></script></body></html>'); grunt.log.ok('Initialized src/ structure.'); });

执行npm run init，5 秒内生成可运行的最小闭环：src/scss/main.scss→build/css/main.css→src/templates/index.html能正确显示。

4.2 日常开发：从改一行 SCSS 到页面刷新的完整链路

这才是加速的核心价值。以修改导航栏背景色为例，走一遍真实流程：

场景：客户说“导航栏太灰，要改成蓝色”。

步骤 1：编辑源码

# 编辑变量文件 vim src/scss/_variables.scss # 修改为：$primary: #0056b3;

步骤 2：Grunt 自动触发由于watch配置了：

watch: { scss: { files: ['src/scss/**/*.scss'], tasks: ['sass:dev', 'shell:checkCssSize', 'sync:css'] } }

保存文件瞬间，终端输出：

>> File "src/scss/_variables.scss" changed. Running "sass:dev" (sass) task >> Generated build/css/main.css Running "shell:checkCssSize" (shell) task >> main.css size OK Running "sync:css" (sync) task >> Copied 1 file Completed in 1.8s at Thu Mar 16 2023 10:22:34 GMT+0800 (CST) - Waiting...

步骤 3：BrowserSync 自动刷新BrowserSync 的代理服务器（http://localhost:3000）检测到build/css/main.css变更，向所有连接的浏览器发送 reload 指令。Chrome DevTools 的 Network 面板显示：

• GET http://localhost:3000/build/css/main.css?t=1678933354231（200，1.2KB）
• GET http://localhost:3000/（200，HTML 页面）

页面在 2.3 秒后刷新，导航栏已变为深蓝色。整个过程无需手动操作，手指离开键盘，眼睛盯着屏幕即可。

步骤 4：验证 Plone 环境此时build/css/main.css已就绪，但 Plone 还没加载。执行：

# 重新启动 Plone 实例（只需一次） bin/instance fg # 或者，如果已启用 plone.app.theming 的自动重载 curl -X POST http://admin:admin@localhost:8080/Plone/@@theming-controlpanel/reload

Plone 会重新读取build/下的文件，++resource++mytheme/css/main.css返回新样式。注意：reload端点只在开发环境开启，生产环境必须走bin/buildout更新。

4.3 构建发布：如何生成 100% 可部署的build/目录？

npm run build不是简单地跑一遍grunt build，而是一套防错流水线：

grunt.registerTask('build', [ 'clean:build', 'svgmin:dist', 'webfont:icons', 'sass:prod', 'requirejs:compile', 'copy:static', 'shell:checkBuildIntegrity' ]);

• clean:build：先清空build/，避免旧文件残留。
• svgmin:dist：预处理 SVG，确保图标质量。
• webfont:icons：生成字体文件（.woff,.ttf,.eot）和 CSS。
• sass:prod：用outputStyle: 'compressed'编译 CSS，体积减少 60%。
• requirejs:compile：打包 JS，optimize: 'uglify2'压缩后体积减少 45%。
• copy:static：把src/images/下的 PNG/JPG 复制到build/images/，不压缩（保持原画质）。
• shell:checkBuildIntegrity：终极校验。

shell:checkBuildIntegrity的脚本是灵魂：

# 检查 build/ 下关键文件是否存在且非空 for f in build/css/main.css build/js/main.min.js build/fonts/mytheme-icons.woff; do if [ ! -s "$f" ]; then echo "FATAL: $f is missing or empty!"; exit 1; fi done # 检查 registry.xml 中声明的路径，是否在 build/ 下存在 grep -o '++resource++mytheme/[^"]*' profiles/default/registry.xml | while read p; do local_path=$(echo $p | sed 's/++resource++mytheme\///') if [ ! -e "build/$local_path" ]; then echo "FATAL: $p declared but build/$local_path not found!"; exit 1; fi done echo "BUILD INTEGRITY CHECK PASSED."

这个脚本确保：你提交到 Git 的build/目录，和客户服务器上解压出来的目录，100% 一致。没有“本地能跑，服务器报 404”的尴尬。

4.4 BrowserSync 代理配置：如何让预览页完美模拟 Plone 环境？

grunt-browser-sync的默认配置是静态服务器，但 Plone 主题需要动态上下文。关键配置：

browserSync: { dev: { bsFiles: { src: [ 'build/**/*', 'src/templates/**/*' ] }, options: { proxy: 'localhost:8080', // 代理到 Plone 实例 port: 3000, open: 'local', // 自动打开 localhost:3000 notify: false, // 关闭右上角弹窗，避免遮挡 Plone UI snippetOptions: { rule: { match: /<\/body>/i, fn: function (snippet) { return snippet + '<script>document.addEventListener("DOMContentLoaded",function(){if(window.location.pathname==="/"){window.location.href="/Plone";}});</script>'; } } } } } }

snippetOptions.rule是神来之笔。它在页面</body>前注入一段 JS，当访问http://localhost:3000/（BrowserSync 根路径）时，自动跳转到http://localhost:3000/Plone，也就是 Plone 的首页。这样，你不用记住http://localhost:3000/Plone/@@theming-controlpanel，直接http://localhost:3000就进入 Plone 环境。而且，proxy模式下，所有http://localhost:3000/Plone/++resource++mytheme/请求，都会被转发到http://localhost:8080/Plone/++resource++mytheme/，但build/下的文件优先级更高——也就是说，http://localhost:3000/Plone/++resource++mytheme/css/main.css返回的是build/css/main.css，而http://localhost:3000/Plone/++resource++plone/返回的是 Plone 原生资源。这种混合模式，让你在真实 Plone 环境里，只替换自己主题的文件，其他一切照旧。

5. 常见问题与排查技巧实录

5.1 “CSS 改了，但页面没变” —— 缓存链路排查四步法

这是最高频问题，根源往往不在 Grunt，而在多层缓存叠加。按顺序排查：

实操心得：我写了一个cache-bust任务，一键清理所有缓存：

shell: { cacheBust: { command: 'curl -X POST http://admin:admin@localhost:8080/Plone/@@theming-controlpanel/reload 2>/dev/null; echo "Plone cache reloaded"; browser-sync reload; echo "BrowserSync reloaded"' } }

执行grunt shell:cacheBust，3 秒解决 90% 的“没变化”问题。

5.2 “Grunt watch 卡死，CPU 占用 100%” —— 文件监听优化

watch默认监听所有子目录，当node_modules/或.git/过大时，会触发海量fs.watch事件。解决方案是精准排除：

watch: { scss: { files: ['src/scss/**/*.scss'], tasks: ['sass:dev'], options: { spawn: false, // 禁用子进程，避免 fork 爆炸 event: ['added', 'changed'], // 忽略 deleted 事件，减少干扰 interrupt: true, // 新事件到来时，中断正在执行的任务 debounceDelay: 500 // 防抖，连续修改 500ms 内只触发一次 } } }

spawn: false是关键。默认spawn: true会为每个任务 fork 一个新 Node 进程，10 次保存就起 10 个进程。spawn: false让所有任务在同一个进程中串行执行，CPU 占用从 100% 降到 15%。

5.3 “图标字体不显示，控制台报 Failed to decode downloaded font” —— MIME 类型修复

Nginx/Apache 默认不识别.woff文件的 MIME 类型，返回text/plain，浏览器拒绝加载。Grunt 本身无法修复服务器配置，但可以在build/目录下生成.htaccess作为提醒：

copy: { htaccess: { files: [{ expand: true, cwd: 'src/config/', src: ['.htaccess'], dest: 'build/' }] } }

src/config/.htaccess内容：

AddType application/font-woff .woff AddType application/font-woff2 .woff2 AddType application/vnd.ms-fontobject .eot AddType application/x-font-ttf .ttf

部署时，把这个.htaccess放到build/目录，再让运维同事把它复制到 Web 服务器的对应路径。这是“人肉 CI”，但比写文档靠谱 10 倍。

5.4 “RequireJS 报错 Uncaught Error: Module name ‘jquery’ has not been loaded yet for context” —— 路径映射陷阱

这个错误不是 jQuery 没加载，而是paths映射错了。常见错误：

• paths: { 'jquery': 'js/jquery.min.js' }→ 错！js/jquery.min.js是相对baseUrl的路径，但baseUrl是src/js，所以实际找的是src/js/js/jquery.min.js。
• 正确写法：paths: { 'jquery': '//code.jquery.com/jquery-3.6.0.min.js' }（CDN）或 `paths: { 'jquery': '../vendor/jquery.min.js'