不注入路径,注入文件内容:gulp-inject 模板预包含完整教程

原创2026-11-13 10:36:28420 阅读
文章标签:开发工具

不注入路径,注入文件内容: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 静默成功日志 按需

常见坑位清单

  1. 忘了去掉 {read: false} —— 源文件内容没被读取,file.contents 为空,注入结果是空字符串。
  2. transform 没有返回字符串 —— 返回 undefined 的文件会被直接跳过,不会报错,容易造成“注入少了文件”的错觉。
  3. 起止标签不配对 —— 找到 starttag 却找不到 endtag 时,gulp-inject 会抛出 Missing end tag for start tag 错误(见 src/inject/index.js)。
  4. 片段中有注释标签 —— 如果 partial 内部恰好含有 <!-- endinject --> 之类的文本,会被误判为结束标签,片段命名时注意避开。
  5. 注入顺序不稳定 —— 多个片段需要固定顺序时,可搭配 stream-series 等插件控制源流顺序,详见 README.md。

小结

gulp-inject 不止是“自动加 script 标签”的工具:只要用一个返回 file.contents.toString('utf8') 的 transform 替换默认行为,再配合 {{ext}} 或 {{path}} 占位符,就能把文件内容直接预包含进模板。记住两件事——内容注入必须读取文件内容(去掉 {read: false})、自定义 transform 决定注入什么——你就能用它搭出自动拼装 HTML 片段的构建流程,从此告别手动编辑 index.html。

登录后查看全文
gulp-inject