Gulp快速入门教程:用gulp-inject一键自动注入所有JS和CSS引用
Gulp快速入门教程:用gulp-inject一键自动注入所有JS和CSS引用
gulp-inject 是 Gulp 构建工具链中一个实用的文件引用注入插件,它能自动把 JavaScript、CSS 等静态资源的 <script>、<link> 标签写入 HTML 模板的占位符中,让你彻底告别手动维护 index.html 的痛苦。本教程面向 Gulp 新手,带你从零配置到跑通第一个自动注入任务。
为什么需要 gulp-inject?
做过前端项目的人都有这个烦恼:
- 每新增一个 JS 或 CSS 文件,都要手动去 HTML 里加一行引用;
- 文件被删除或改名后,引用经常忘记同步,页面直接报错;
- 项目大了之后,
index.html里几十行引用手动维护极易出错。
gulp-inject 的思路非常直观:在 HTML 中留一对注释占位符,构建时它扫描你的源码目录,把匹配到的文件自动转换成标签注入进去。增删文件后重新跑一次 Gulp 任务,引用始终和源码保持同步 ✅
插件还支持向
html、pug、jade、jsx、less、slm、haml、sass、scss等模板文件注入引用,不只是 HTML。
快速安装步骤
在项目根目录执行:
npm install --save-dev gulp-inject
作为构建工具,它通常安装为开发依赖即可。版本信息可参考 package.json。
三步跑通第一个注入任务
第一步:在 HTML 中放置占位符
占位符就是成对的注释,默认格式为 <!-- inject:扩展名 --> 与 <!-- endinject -->:
<!DOCTYPE html>
<html>
<head>
<title>My index</title>
<!-- inject:css -->
<!-- endinject -->
</head>
<body>
<!-- inject:js -->
<!-- endinject -->
</body>
</html>
这样 CSS 引用会进 <head>,JS 引用会进 <body>,一步到位。
第二步:编写 gulpfile.js
var gulp = require('gulp');
var inject = require('gulp-inject');
gulp.task('index', function () {
var target = gulp.src('./src/index.html');
// read: false 表示只取文件路径,不读文件内容,速度更快
var sources = gulp.src(['./src/**/*.js', './src/**/*.css'], {read: false});
return target.pipe(inject(sources))
.pipe(gulp.dest('./src'));
});
小技巧:gulp.src 加上 {read: false} 后只收集路径不读内容,可以明显提升大项目下的构建速度。
第三步:运行任务,查看结果
gulp index
运行后,src/index.html 会被自动更新为:
<head>
<!-- inject:css -->
<link rel="stylesheet" href="/src/style1.css">
<link rel="stylesheet" href="/src/style2.css">
<!-- endinject -->
</head>
<body>
<!-- inject:js -->
<script src="/src/lib1.js"></script>
<script src="/src/lib2.js"></script>
<!-- endinject -->
</body>
从此之后,src 目录里新增或删除任何 JS/CSS 文件,重跑一次任务即可自动同步 🎉
常用选项速查表
gulp-inject 的选项不多但都很实用,以下是新手最常用的几个(完整说明见 README.md):
| 选项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
relative |
Boolean | false |
注入路径改为相对于每个目标文件所在目录 |
ignorePath |
String / Array | null |
从注入路径中去除指定的路径前缀 |
addPrefix / addSuffix |
String | null |
给注入路径统一加前缀/后缀 |
addRootSlash |
Boolean | !relative |
控制路径开头是否带 / |
name |
String | "inject" |
自定义占位符名称,如 <!-- bower:js --> |
starttag / endtag |
String / Function | 按文件类型自动生成 | 自定义占位符的开始/结束标签 |
transform |
Function | 内置默认转换 | 自定义每个文件如何被转成标签 |
removeTags |
Boolean | false |
注入后移除占位符注释本身 |
selfClosingTag |
Boolean | false |
让 <link> 等标签自闭合 |
quiet |
Boolean | false |
关闭控制台日志输出 |
场景一:注入相对于目标文件的路径
多页面项目中,每个 HTML 页面距离资源的路径深度不同,绝对路径就不好用了。设置 relative: true 后,每个目标文件会获得自己的相对路径:
.pipe(inject(gulp.src('./src/**/*.js', {read: false}), {relative: true}))
场景二:同一页面注入到不同位置
想让个别重要脚本进 <head>、其余进 <body>?用 starttag 区分不同的占位符即可:
gulp.src('./src/index.html')
.pipe(inject(gulp.src('./src/importantFile.js', {read: false}),
{starttag: '<!-- inject:head:{{ext}} -->'}))
.pipe(inject(gulp.src(['./src/*.js', '!./src/importantFile.js'], {read: false})));
HTML 中对应写两对占位符:<!-- inject:head:js --> 和 <!-- inject:js -->。
场景三:合并多个资源流
当你把 vendor 代码和应用代码分别打包后再注入时,可以用 event-stream 的 merge 合并多个流;如果顺序很重要(比如 vendor 必须在应用代码之前),可以使用 stream-series 串联流,保证注入顺序稳定。
它是怎么工作的?源码导读
想深入了解实现细节,可以看看这几个核心模块:
- index.js:包入口,导出主插件及内置
transform; - src/inject/index.js:注入主流程,负责扫描占位符并执行替换;
- src/tags/index.js:各模板类型(html/pug/less/scss 等)的默认占位符规则;
- src/transform/index.js:内置的文件→标签转换函数,如 js 转
<script>、css 转<link>; - src/path/index.js:注入路径的拼接与处理逻辑。
测试用例中还有大量现成示例可供参考,例如 src/inject/fixtures/template.html 展示了多组 <!-- inject:xxx --> 占位符的写法,src/inject/inject_test.js 与 src/inject/expected/ 目录则给出了各种选项下的预期注入结果。
常见问题 FAQ
Q:注入后路径带了不想要的 /src 前缀?
用 ignorePath: './src' 把前缀去掉,或改用 cwd 选项、relative: true。
Q:占位符注释想保留还是删掉?
默认保留(方便下次继续注入);设置 removeTags: true 可在注入后移除注释。
Q:能用自定义标签格式吗?
可以。starttag/endtag 支持字符串或函数,且内置 {{ext}}、{{name}}、{{path}} 占位变量,能按扩展名动态生成不同的注释标签。
Q:注入顺序和我 gulp.src 写的顺序不一致?
gulp.src 的文件顺序不保证稳定,重要场景请用 stream-series 显式控制顺序。
总结
gulp-inject 用极低的配置成本解决了"HTML 引用手动维护"这一经典痛点:一对注释占位符 + 一个 Gulp 任务,就能让所有 JS/CSS 引用随源码自动更新。建议按本文的三步走流程先跑通基础场景,再按需挑选 relative、starttag、transform 等选项应对更复杂的项目结构。
核心资料导航:
- 完整选项文档:README.md
- 插件主逻辑:src/inject/index.js
- 内置转换函数:src/transform/index.js