<p>必须使用成对且格式严格的<!-- inject:css -->和<!-- endinject -->注释占位符，src需指向已编译CSS文件，启用relative: true生成相对路径，按字典序命名或用gulp-sort控制注入顺序，并校验文件存在性。</p>
用 gulp-inject 注入 CSS 到 HTML，必须写对注释占位符
不写或写错注释，gulp-inject 就找不到插入位置，最终 HTML 里什么都不会加。它只认特定格式的 HTML 注释，不是随便写个 <!-- css --> 就行。
默认识别的占位符是：
<!-- inject:css --> <!-- endinject -->
这对注释必须成对出现、且完全匹配大小写和空格。常见错误包括：
- 写成
<!-- inject:css --><!-- endinject -->（没换行，但其实不影响） - 写成
<!-- inject:CSS -->（大写 CSS，不匹配） - 漏掉
endinject，导致后续所有注入都失败 - 把注释放在
<script>标签内部（gulp-inject不解析标签内容，只扫描纯注释）
gulp-inject 的 src 路径必须指向已编译好的 CSS 文件
很多人卡在这一步：在 gulpfile.js 里写了 src(['./src/**/*.css'])，但源目录里只有 .scss，根本没生成 CSS —— 结果注入的是空流，HTML 里啥也不加。
立即学习“前端免费学习笔记（深入）”；
正确做法是确保注入前已完成编译，例如：
- 先跑
gulp-sass或gulp-less把预处理器文件输出到./dist/css/ - 再让
inject任务读取./dist/css/*.css - 不要跨阶段混用路径，比如
src('src/**/*.scss')直接传给inject()，它不会自动编译
示例片段：
const inject = require('gulp-inject');
const injectCss = () => {
const target = src('./dist/index.html');
const sources = src('./dist/css/*.css', { read: false }); // read: false 提速，只取路径
return target.pipe(inject(sources, { relative: true }))
.pipe(dest('./dist'));
};启用 relative: true 才能生成相对路径引用
默认注入的路径是绝对路径（如 /css/main.css），但多数静态服务不走根路径，直接打开 HTML 会 404。设 relative: true 后，插件会按目标 HTML 和资源文件的物理位置算出相对路径，比如 HTML 在 dist/index.html，CSS 在 dist/css/main.css，就注入 css/main.css。
注意两个关键点：
-
relative: true依赖文件实际磁盘路径，不是gulp.src()的 glob 路径 - 如果 CSS 输出到了
dist/assets/css/，但 HTML 还在dist/，注入结果就是assets/css/main.css，别指望它自动“向上跳级” - 若需强制加前缀（如 CDN 域名），用
addPrefix: 'https://cdn.example.com/'，但它和relative互斥，开了relative就别配addPrefix
多个 CSS 文件注入顺序不可控，需靠文件名或 sort 控制
gulp-inject 按 src() 返回的 stream 顺序注入，而 Node.js 的 fs.readdir 顺序不保证稳定 —— 今天可能是 reset.css 在前，明天变成 main.css 在前。这对依赖顺序敏感的项目很危险（比如 normalize.css 必须在 main.css 之前）。
解决方法只有两种：
- 统一命名前缀，如
00-reset.css、01-base.css、02-main.css，靠字典序稳住 - 用
sort插件手动排序，例如：const sort = require('gulp-sort'); // ... sources.pipe(sort({ comparator: (a, b) => a.relative.localeCompare(b.relative) }))
别依赖 gulp.src(['a.css', 'b.css']) 的数组顺序 —— glob 匹配后仍可能被底层文件系统打乱。
最容易被忽略的是：注入动作本身不校验文件是否存在或是否为空。哪怕 ./dist/css/ 目录下啥都没有，gulp-inject 也会安静地完成任务，HTML 里只留一对空注释。上线前务必手动检查输出目录结构，或加一层 gulp-if + gulp-plumber 做存在性断言。
