不注入路径,注入文件内容:gulp-inject 模板预包含完整教程
不注入路径,注入文件内容:gulp-inject 模板预包含完整教程
如果你还在手动往 index.html 里复制粘贴 <script>、<link> 标签,那么 gulp-inject 这个 Gulp 插件值得你了解。它默认帮你自动注入 js、css、webcomponent 等文件的路径引用,但很多人不知道的是:通过一个自定义 transform 函数,gulp-inject 还能跳过路径、直接把文件的完整内容预包含进模板,实现 HTML 片段的自动拼装。本文将带你完整掌握这条进阶路线。
先搞懂两种注入模式的区别
理解这一点,是后面所有操作的根基:
| 维度 | 默认模式:注入路径 | 进阶模式:注入内容 |
|---|---|---|
| 注入结果 | <script src="/app/main.js"></script> 这样的标签 |
文件内部的真实代码/HTML 片段 |
| 典型用途 | 给页面挂载脚本、样式、组件引用 | 预包含 HTML 局部片段(partial) |
gulp.src 选项 |
加 {read: false} 提速(只取路径) |
必须省略 {read: false}(要读内容) |
transform 选项 |
使用内置默认值即可 | 必须自定义,返回 file.contents.toString('utf8') |
核心逻辑在 src/inject/index.js 的 getTagsToInject 中:每个源文件都会调用一次 transform,把返回的字符串塞进起止标签之间。默认 transform 生成的是带路径的标签(见 src/transform/index.js),而换成“返回文件内容”的 transform,就切换到了内容注入模式。
一键安装:最快上手步骤
在项目中执行以下命令安装开发依赖:
npm install --save-dev gulp-inject
然后在 gulpfile.js 顶部引入:
var inject = require('gulp-inject');
安装完成后,你就可以开始配置模板占位符了。
场景一:把 HTML 片段内容注入指定区域
这是最常用的“模板预包含”场景:把 partials/ 目录下的 HTML 片段直接展开到 index.html 的 <head> 里。
1. 在模板中放置占位符(src/index.html):
<head>
<title>My index</title>
<!-- inject:head:{{ext}} -->
<!-- endinject -->
</head>
{{ext}} 会被自动替换为源文件的扩展名(如 html),这个替换逻辑实现在 src/tags/index.js。
2. 配置 gulpfile.js:
gulp.src('./src/index.html')
.pipe(inject(gulp.src(['./src/partials/head/*.html']), {
starttag: '<!-- inject:head:{{ext}} -->',
transform: function (filePath, file) {
return file.contents.toString('utf8');
}
}))
.pipe(gulp.dest('./dest'));
注意两个关键点:
- 没有
{read: false}—— 这样file.contents才有内容可读; transform返回file.contents.toString('utf8')—— 把片段原文而非路径作为注入内容。
运行后,partials/head/ 里每个片段的完整 HTML 都会被展开进占位符之间,页面打开即可用,无需额外加载请求。
场景二:用 {{path}} 按文件路径精确包含
如果每个片段的注入位置是独立的(每个 partial 一个专属占位符),可以使用 {{path}} 占位符,让每个源文件只匹配自己路径对应的位置:
gulp.src('./src/index.html')
.pipe(inject(gulp.src(['./src/partials/head/*.html']), {
starttag: '<!-- inject:{{path}} -->',
relative: true,
transform: function (filePath, file) {
return file.contents.toString('utf8');
}
}))
.pipe(gulp.dest('./dest'));
配合相对路径模板:
<!-- inject:path/to/your/file.ext -->
<!-- endinject -->
{{path}} 会被替换为源文件路径(relative: true 时为相对路径),路径计算规则见 src/path/index.js。这个模式适合“每个模块固定包含到固定位置”的页面架构,官方测试用例可参考 inject_test.js 中 {{path}} 相关的验证逻辑。
关键参数速查表
| 参数 | 类型 | 作用 | 本文中的取值 |
|---|---|---|---|
transform |
Function | 决定每个文件注入什么内容 | 返回 file.contents.toString('utf8') |
starttag / endtag |
String | 定义起止占位符,支持 {{ext}}、{{name}}、{{path}} 变量 |
<!-- inject:{{path}} --> 等 |
relative |
Boolean | true 时 {{path}} 与注入路径相对目标文件 |
按路径注入时建议 true |
removeTags |
Boolean | 注入后是否移除起止标签 | 按需 |
quiet |
Boolean | 静默成功日志 | 按需 |
常见坑位清单
- 忘了去掉
{read: false}—— 源文件内容没被读取,file.contents为空,注入结果是空字符串。 transform没有返回字符串 —— 返回undefined的文件会被直接跳过,不会报错,容易造成“注入少了文件”的错觉。- 起止标签不配对 —— 找到
starttag却找不到endtag时,gulp-inject 会抛出Missing end tag for start tag错误(见 src/inject/index.js)。 - 片段中有注释标签 —— 如果 partial 内部恰好含有
<!-- endinject -->之类的文本,会被误判为结束标签,片段命名时注意避开。 - 注入顺序不稳定 —— 多个片段需要固定顺序时,可搭配
stream-series等插件控制源流顺序,详见 README.md。
小结
gulp-inject 不止是“自动加 script 标签”的工具:只要用一个返回 file.contents.toString('utf8') 的 transform 替换默认行为,再配合 {{ext}} 或 {{path}} 占位符,就能把文件内容直接预包含进模板。记住两件事——内容注入必须读取文件内容(去掉 {read: false})、自定义 transform 决定注入什么——你就能用它搭出自动拼装 HTML 片段的构建流程,从此告别手动编辑 index.html。