人则水州最近给一个老项目做性能体检，打开Chrome DevTools的Network面板一看，35个CSS和JS文件排得整整齐齐，光是资源请求就有47个。这个项目还是传统的服务端渲染，模板里散落着各种插件、样式库的引用，每次改版都得手动画一张“页面到底引用了哪些文件”的图。想直接上webpack做工程化重构吧，模板引擎、静态资源体系、部署方式全部要动，短期根本排不出这个人力。
所以我就做了个决定：不折腾构建框架，自己写一个HTML资源合并工具，专门干一件事——自动合并CSS/JS，减少请求数。这个工具不依赖任何第三方库，用Node.js原生能力手搓，能解析HTML模板、提取外链样式和脚本、压缩合并成一个文件、自动修复CSS里的相对路径、给文件名加内容Hash做缓存更新，最后把模板里的引用替换掉。整个过程跑一遍只要几百毫秒，项目里所有页面的请求数从47个降到2个。
这篇文章就把这个工具从思路到代码完整拆开讲一遍，包括我自己踩过的坑：@charset位置导致的乱码、CSS变量覆盖顺序出错、JS文件合并后的作用域污染、字体文件404等等。适合正在做传统多页面项目、又暂时没预算上重型构建工具的前端同学参考。
1. 为什么要合并CSS/JS：先算清请求数这笔账
1.1 一次资源请求到底贵在哪
前端性能优化里有个非常经典的说法：浏览器加载一个页面，请求数越少，首屏越快。这句话在HTTP/1.1时代几乎就是铁律，因为HTTP/1.1对同一域名有并发连接数限制，标准是6个，也就是浏览器最多同时用6个TCP连接去取资源。如果一个页面有40个CSS/JS文件，这些文件要在6个通道里排着队下载，每一个请求都要经历DNS解析、TCP握手、TLS协商（HTTPS还要多两个RTT）、发送请求头、服务器处理、响应返回这一整条链路。
咱们简单地算笔账。假设网络RTT（往返延迟）是50ms，服务器处理请求平均50ms，那一个请求从发出到拿到数据大约就是100ms。40个文件分到6个连接上，平均每个连接要处理约7个文件，串行排队的总耗时就是 7 × 100ms = 700ms，这还没算浏览器解析、渲染、执行脚本的时间。如果把40个文件合并成2个，下载时间基本可以控制在200~300ms以内，光这一项就能省下400~500ms。在移动端弱网环境下，RTT涨到200ms甚至更高，这个差距会进一步拉大到几秒钟，危害非常直接。
有人会说，现在都HTTP/2了，多路复用不是能同时传多个文件吗？这话没错，HTTP/2确实打破了同域名6个连接的限制，一个TCP连接里可以并发传输所有文件。但HTTP/2的推广远没有想象中那么彻底，很多内网系统、老旧服务器、第三方CDN仍然跑在HTTP/1.1上，而且就算用了HTTP/2，几十个文件的请求头开销、服务器IO压力、移动端网络波动也依然存在。所以“合并资源、减少请求数”这个手段，在今天仍然是性价比很高的优化方案，尤其对于中小型站点和传统服务端渲染项目来说。
1.2 三种资源合并方案，为什么我选择手搓脚本
资源合并这件事，业界已经有了不少成熟工具。最典型的是构建工具链方案，用webpack或者Vite做打包，把所有CSS通过import引入，JS按模块拆分，构建后自动产出合并文件。gulp生态里也有gulp-concat、gulp-clean-css这类插件，配一条流水线任务就能做文件合并压缩。
还有一种方案是用现成的在线压缩合并服务，把文件贴上去，一顿操作拿到一个合并后的文件下载回来。这种方式最省事，但问题也很明显：不可复现、不能接入自动化流程、不好处理相对路径和缓存更新，整个流程是黑盒的，出了问题你根本不知道它在哪一步动了手脚。
我最终选择自己用Node.js写脚本，核心原因有三个。第一是可控，整个工具逻辑就几个函数，每行代码都看得懂，改起来非常灵活，比如我想针对某个目录例外处理，加一个if判断就行，不用去翻webpack文档找loader配置。第二是零依赖，不需要npm install任何东西，Node.js自带的fs、path模块就够了，脚本拷到任何一台服务器上都能直接跑，连node_modules都不用装。第三是和项目现状匹配，传统多页面项目的资源引用方式基本就是和。
3.2 合并CSS：顺序、@import与相对路径修复
CSS合并的难点在于顺序问题。CSS的执行顺序对样式计算结果有直接影响，后面定义的样式如果选择器优先级相同，会覆盖前面的定义。所以合并CSS时必须保持文件在HTML里出现的顺序，不能乱。
合并的代码逻辑是：按cssList的顺序依次读取文件内容，用换行拼接起来。但正常开发情况下，一个CSS文件里往往用了相对路径的url()来引用图片和字体。比如某个文件在assets/css/theme.css，里面写url(../images/logo.png)，这个路径是相对于theme.css所在目录的。合并后新文件放到dist/css/下，如果直接拼进去，浏览器会按照dist/css/目录去解析url(../images/logo.png)，结果去找dist/images/logo.png，而实际文件在assets/images/logo.png，必然404。
所以合并CSS时必须重写所有url()的相对路径。我的做法是：拿到每个CSS文件的绝对路径，读取内容后遍历所有url()引用，如果是data:、http、//、/开头的绝对地址就跳过，剩下的相对路径用path.resolve转成基于项目根目录的绝对路径，再相对于合并后的新CSS文件的输出目录重新计算相对路径：
javascript复制function fixCssUrls(cssContent, cssFilePath, outputCssDir) {
const cssDir = path.dirname(cssFilePath);
return cssContent.replace(/url\((['"]?)([^)'"]+)\1\)/g, (match, quote, url) => {
if (/^(data:|https?:|\/\/|\/|#)/i.test(url)) return match;
if (url.startsWith('http')) return match; // 兜底再判断一次
const absolute = path.resolve(cssDir, url);
let rel = path.relative(outputCssDir, absolute);
rel = rel.split(path.sep).join('/'); // Windows路径分隔符统一转成/
return `url(${quote}${rel}${quote})`;
});
}
这个正则匹配的是url(...)这种写法，可以兼容url()、url('')、url("")三种形式。quote变量保留原来的引号样式，避免改变文件的编码习惯。
另一个容易踩坑的点是@import规则。CSS规范里@import必须写在样式表的最前面，而且一般不建议用@import加载样式，因为它会阻塞渲染，相当于把一组请求串行化了。如果合并时遇到某个文件里有@import "./base.css"，不能直接在文件当前位置拼接，需要把@import的内容递归解析出来，并把所有@import语句提升到合并后CSS文件的顶部。我实际处理方式是：遇到@import就先递归读取目标文件内容，然后把这条@import语句从原文件中删除，最后在合并输出时把所有内联的@import内容放在最前面：
javascript复制function resolveCssImports(cssContent, cssFilePath, outputCssDir, visited = new Set()) {
const importRe = /@import\s+["']([^"']+)["']\s*;/g;
let resolved = cssContent;
let importChunks = [];
let match;
while ((match = importRe.exec(cssContent)) !== null) {
const importPath = match[1];
if (/^(https?:|\/\/)/i.test(importPath)) continue; // 外链@import不处理
const importAbs = path.resolve(path.dirname(cssFilePath), importPath);
if (visited.has(importAbs)) continue; // 防死循环
visited.add(importAbs);
const importContent = fs.readFileSync(importAbs, 'utf8');
const subResult = resolveCssImports(importContent, importAbs, outputCssDir, visited);
importChunks.push(subResult.resolved);
resolved = resolved.replace(match[0], '');
}
if (importChunks.length > 0) {
resolved = importChunks.join('\n') + '\n' + resolved;
}
return { resolved };
}
这里我设置了一个visited集合来防止循环引入，比如a.css引用了b.css，b.css又引用了a.css，不处理的话就会无限递归，直接爆栈。这个防护是必须的。
3.3 合并JS：BOM头、分号与依赖顺序
JS合并相对CSS简单一些，但有几个细节如果不处理，线上就等着报错。
第一个是BOM头问题。Windows下用记事本保存的JS文件经常带一个UTF-8 BOM头（字节序EF BB BF），在文件最前面。单个文件加载时浏览器能识别，但多个文件拼接后，如果某个文件的BOM头出现在中间，浏览器解析到这里就会遇到非法字符，直接报语法错误。所以读取JS文件后第一件事就是去掉BOM：
javascript复制function stripBom(content) {
if (content.charCodeAt(0) === 0xFEFF) {
return content.slice(1);
}
return content;
}
第二个是分号问题。有的JS文件压缩后结尾没有分号，如果下一个文件开头是一个函数调用开始的表达式，两个文件拼接后就可能被解析成同一个语句。最常见的情况是前一个文件以函数表达式结尾，比如;(function(){})()，后一个文件以[]开头，用来做代码缩混淆。虽然这种写法不常见，但为了安全，我统一在每个文件内容后面加一个分号再拼接：
javascript复制function mergeJsFiles(jsList, outputDir) {
const chunks = jsList.map(item => {
const content = stripBom(fs.readFileSync(item.absolutePath, 'utf8'));
return content.endsWith(';') ? content : content + ';';
});
const merged = chunks.join('\n');
// 写文件和hash处理...
}
第三个是依赖顺序。JS文件之间如果有依赖关系，比如a.js调用b.js里定义的函数，合并后a.js必须在b.js后面，否则函数还没定义就执行了。但这里要区分两种情况：如果依赖关系发生在文件加载阶段，比如在代码顶层就调用，那顺序就非常重要，出错了很难排查。如果依赖关系只发生在用户交互的回调函数里，那顺序反而不敏感。所以我设计工具时没有自动分析依赖关系，而是保留了模板里script标签的原始顺序，同时在文档里提醒使用者：合并前先确认JS文件之间的依赖顺序，必要的话手工调整一下模板里的引用顺序。
3.4 生成版本化文件名并改写HTML引用
资源合并完成之后，下一步就是把生成的合并文件写到输出目录，然后改写HTML引用。这个环节要注意的是：不能简单地把每个旧标签替换成新标签，因为页面里的CSS和JS有几十个，合并后只需要保留一个CSS引用和一个JS引用，其他标签要删掉。如果直接用replace做全局替换，会把页面里原本想保留的外链脚本也误伤。
所以我的替换逻辑是：先处理CSS引用，找到页面里第一个本地CSS标签的位置，把它替换成合并后的CSS标签，然后把其余本地CSS标签删除。处理JS同理：
javascript复制function replaceAssets(html, cssResult, jsResult) {
let output = html;
// 替换CSS：第一次出现本地label的位置替换，后续全部删除
if (cssResult.cssList.length > 0) {
let cssReplaced = false;
const localCssRe = /<link\b[^>]*rel=["']stylesheet["'][^>]*>/gi;
output = output.replace(localCssRe, (tag) => {
if (isLocalCssTag(tag)) {
if (!cssReplaced) {
cssReplaced = true;
return `<link rel="stylesheet" href="${cssResult.filename}">`;
}
return '';
}
return tag; // 外链标签保留
});
}
// 替换JS类似...
return output;
}
这里的isLocalCssTag函数就是判断当前标签是否在cssList里，可以用标签的原始字符串做匹配。由于外链标签或黑名单标签不在cssList里，replace回来时原样保留。
文件名引用这里有个细节：html里引用路径要用绝对路径还是相对路径？我生成的HTML放在outputDir根目录，合并后的CSS/JS放在outputDir/css/和outputDir/js/下面，所以引用路径写成/css/app.8f3a2b.css和/js/app.8f3a2b.js。这样只要outputDir部署到网站根目录，路径就不会错。如果你的项目静态资源会挂到CDN域名下，这里可以把href前缀替换成CDN域名，用同样一套模板就能区分不同环境的部署。
写完文件后，我会在控制台里打印替换前后的资源数量对比，方便确认：
javascript复制const oldCssCount = extracted.cssList.length;
const oldJsCount = extracted.jsList.length;
const newCssCount = (output.match(/<link[^>]+rel=["']stylesheet["']/gi) || []).length;
const newJsCount = (output.match(/<script[^>]+src=/gi) || []).length;
console.log(`CSS: ${oldCssCount} -> ${newCssCount}`);
console.log(`JS: ${oldJsCount} -> ${newJsCount}`);
如果输出里显示CSS的数量是1，说明合并成功；如果还是原来的数量，那就要检查正则匹配是否有遗漏。
4. 踩坑实录与排查技巧
4.1 相对路径导致的字体图片全部404
第一次跑完合并，在浏览器里打开页面，样式是乱的，控制台里一长串404，全是字体文件和背景图片。定位后发现就是CSS里url()相对路径没有重写导致的。这个问题的根源也很清楚：CSS文件放在assets/css/目录下，里面的相对url是相对自己目录算的，合并后文件位置变了，相对关系自然全错。
排查这种问题有一个很实用的小技巧：在浏览器控制台里看404请求的URL，对比一下实际文件路径，就能判断出是路径前缀多了还是少了。比如404的URL是dist/images/logo.png，而实际文件在assets/images/logo.png，那就是路径少了assets这一层，说明重写逻辑里把相对路径算错了。我修复后的代码会在重写时把路径统一转成相对输出CSS目录的相对路径，而不是保留原有的相对关系，这样就不会受源文件目录结构影响了。
另外，处理url()正则时一定要考虑引号问题。有的CSS写成url("data:image/png;base64,...")，里面可能包含括号、分号等特殊字符，如果正则的捕获组写得不对，会截断或者误判。我最终用的正则是url((['"]?)([^)'"]+)\1)，它的原理是：url(后面可以跟单引号、双引号或者什么都不跟，然后用反向引用\1确保结尾和开头的引号一致，中间用[^)'"]+匹配除括号和引号外的所有字符，这样base64内容也能被完整匹配到。
4.2 @charset位置错误导致中文乱码
另一个让我印象深刻的坑是CSS文件里的@charset声明。如果在合并后的CSS文件中间出现了@charset "UTF-8";，浏览器会忽略它，而CSS又没有声明文件编码时，里面用中文写的content: "你好"就会变成乱码。
事情的经过是：我有两个CSS文件，文件A开头有@charset "UTF-8";，文件B没有。合并后A的内容在中间，它头上的@charset也被带到了合并文件的中间位置。浏览器解析CSS时，只有出现在文件最开头的@charset才生效，中间的会被当作普通规则忽略，结果就是A文件里所有中文内容全部乱码。
解决这个问题很简单：读取CSS文件时，把开头的@charset声明剥离掉，合并输出时在最顶部统一补上@charset "UTF-8";。CSS文件一般都用UTF-8编码，统一声明不会出错。如果项目里混用了GBK编码的老样式文件，需要先转码再合并，这个属于特殊情况，在工具里提供一个可选的编码转换回调接口即可。
4.3 CSS合并后样式错乱的三个原因
CSS合并后出现样式错乱，原因往往比路径问题更隐蔽。我排查了一圈下来，最常见的三个原因分别是：变量覆盖顺序变化、选择器优先级冲突、字体声明被截断。
变量覆盖顺序的问题是：CSS自定义属性（var(--primary-color)这种）的取值取决于定义它们的规则在样式表中的位置。假设文件A里:root { --primary: #f00; }，文件B里:root { --primary: #00f; }，合并后文件B出现在文件A之后，最终生效的变量值是文件B的蓝色。这在单个文件加载时可能不会出问题，因为两个文件之间的加载顺序和合并后的顺序如果一致就没影响，但如果合并时对文件排序了，就会出现“页面突然整体换色”的诡异现象。所以合并CSS时顺序必须严格保持HTML里的引用顺序，不能按文件名排序，也不能按文件大小排序。
选择器优先级冲突则是另一种情况，比如a.css里写了.class-name { color: #f00; }，b.css里以.class-name { color: #00f; }结尾，合并后b文件在后面，蓝色生效。如果两个文件本来在页面里的加载顺序就是a在前b在后，那合并后结果一致，没问题。但如果原来b.css在a.css之前加载，合并后顺序变了，页面颜色就会变化。这个只能靠人工确认合并顺序来保证逻辑不变。
字体声明被截断是实际案例：一个CSS文件里有@font-face规则，其中src属性用逗号分隔了多个url()，比如src: url(font1.woff2) format('woff2'), url(font1.woff) format('woff')。因为我的正则只匹配单个url()，如果处理不当会把逗号后面的部分截掉，导致字体文件加载失败。修复方式是在正则里加入对format的支持，或者在拼接时保证逗号和format原样保留，不破坏字体声明的完整性。
4.4 JS合并后报错的排查思路
JS合并以后报错，排查思路和CSS不太一样。CSS错乱可以用“看样式是否变化”来定位，JS报错则直接看控制台的报错堆栈，重点是堆栈里显示的行号和合并后文件的行号不一定对应原文件。
我第一次遇到这个问题时，控制台报错提示app.8f3a2b.js的第120行有语法错误，但这个行号是合并文件里的行号，很难直接对应到源文件。后来我在合并时给每个文件之间加了明确的注释分隔，方便定位，比如：
javascript复制// ====== source: a.js ======
contentA;
// ====== source: b.js ======
contentB;
这样就可以用报错位置附近的注释快速定位是哪个源文件出问题，非常实用。
还有一个关于全局变量的坑：合并到同一个作用域后，如果一个文件里声明了变量var total = 1，另一个文件里又声明了var total = 2，第二个声明会被提升，第一个变量会被覆盖，但不会报错。如果代码逻辑依赖第一个变量的值，就会出现“某些功能正常、某些功能异常”的奇怪现象。这个问题的排查思路是：在合并前全局搜索一下是否有重复的var声明，或者在合并后用eslint的no-redeclare规则跑一遍。我的工具里提供了一行命令可以输出合并文件里的顶层变量列表，方便做人工审查。
4.5 这个方案的适配边界：什么时候不建议用
这里要说句公道话：资源合并不是万能的，有些场景我建议你慎用甚至不用。如果你正在构建一个大型单页应用，所有JS已经通过ES Module按需加载，这时再手动合并反而会破坏模块系统，应该走webpack或者Vite的正式产物配置。如果你的页面大量使用了动态import、异步组件，合并会让首屏JS包变得特别大，下载时间反而拖慢首屏，这时候优化重点应该是减小包体积而不是减少请求数。
这个手搓方案的适用范围是：传统多页面服务端渲染项目、活动页、CMS系统、后台管理系统，这些项目的资源引用以多个独立CSS/JS文件为主，没有复杂的模块依赖，合并后收益明显且风险可控。另外还有一个关键前提：你的模板系统要支持直接修改HTML输出的内容。如果模板引擎把CSS/JS引用编译得相当复杂，比如由后端配置动态生成，那这个工具就不太好套用，可能需要你把合并逻辑迁移到后端渲染层去。
我在实际使用中还会在构建脚本里加一步：合并完后自动跑一遍页面的冒烟测试，打开首页、点击几个核心交互，看控制台有没有报错。虽然这一步看起来没什么技术含量，但每次改完合并逻辑，它都能在第一时间帮我发现问题，比手动刷新页面靠谱得多。
5. 从一次完整的构建记录看工具的实际效果
工具写完以后，我拿项目里最复杂的一个页面做了实测。这个页面是后台管理系统的首页，原本引用了18个CSS文件、22个JS文件，其中有一部分是第三方库，一部分是业务代码，还有几个是部门同事各自加的插件脚本。
跑完合并后，CSS合并成1个文件，大小约128KB，JS合并成1个文件，大小约340KB（未压缩，服务器端开gzip的话能压到80KB左右）。模板里的资源引用从40个降到了2个。部署到测试环境后用Chrome DevTools的Network面板测加载时间，在模拟Fast 3G网络条件下，页面完全可交互的时间从原来的4.8秒降到了2.1秒，提升了超过一半。如果再把这两个合并文件放到CDN上，或者在构建脚本里接入UglifyJS压缩，数字还能进一步优化。
更让我觉得值的是后续的维护体验。以前改一个公共样式的文件，要等所有页面引用它的缓存过期后才能看到效果，现在只要内容变化，Hash一变，所有页面引用自动指向新文件，不用再手工清缓存。开发环境的构建脚本也顺手加了监听模式：用Node的fs.watch监听模板和资源目录，文件一变化就自动重新合并，保存即生效，跟现代前端框架的热更新体验差不多。
这个工具从写第一行代码到跑通全部流程，耗时大约一个下午。之后我就把脚本放进了项目仓库的scripts/目录下，在package.json里加了两个命令：npm run build:merge（手动执行合并）和npm run watch:merge（监听模式自动合并）。同事如果想用，直接跑一下命令就行，不需要理解里面的实现细节。
6. 说点个人体会
手搓这个HTML资源合并工具之后，我最大的一个体会是：很多看起来高大上的工程化改造，本质上就是把重复劳动脚本化，用最简单的代码解决最具体的问题。webpack很强大，但为了一个传统多页面项目去配置一整套loader、plugin、babel，成本其实很高。而一个200行的Node脚本，足够应对我手头这类项目的日常需求，还顺带让我把CSS、JS的加载机制、缓存策略、相对路径原理彻底过了一遍。
如果你也在维护一个没有构建工具的传统项目，我建议你花点时间试试自己写一套资源合并逻辑。从解析HTML标签开始，到处理路径、Hash、缓存，每一环都会让你对前端性能优化有更具体的认知。工具不用做得大而全，能解决当前项目的问题、能在十分钟内跑完、出错了能快速定位，对我来说就是好工具。遇到更复杂的依赖关系，再迭代进去也不迟。这个项目后续还可以扩展的方向包括：接入压缩器、生成SourceMap、支持多页面入口的批量处理、通过CDN上传接口自动发布静态资源，都是顺手就能加的功能。