选用 gulp + posthtml 是因为纯静态 html5 项目无需 webpack 的模块系统，gulp 专注文件流处理，posthtml 轻量精准操作 html，适合资源注入、路径修正等优化；二者组合构建快、体积小、逻辑透明。
为什么不用 Webpack 而选 Gulp + PostHTML
因为你要打包的是纯静态 HTML5 项目（无 React/Vue 等框架），Webpack 的模块解析和 runtime 注入反而增加冗余、拖慢构建、干扰相对路径引用。Gulp 本身不介入模块系统，只做文件流处理；PostHTML 是轻量级 HTML 转换器，能精准操作标签、属性、注释，适合做资源注入、路径修正、环境变量替换等静态优化任务——二者组合，构建快、体积小、逻辑透明。
安装与基础 gulpfile.js 结构
先确保已装 Node.js（≥16.x）和 npm。全局只需一次：npm install -g gulp-cli；项目内必须装：npm install --save-dev gulp posthtml posthtml-include posthtml-modules posthtml-expressions。注意不要漏掉 --save-dev，否则 gulp 在 gulpfile.js 中 require('gulp') 会报错。
创建 gulpfile.js，用 ES Module 语法（Node ≥14 默认支持）：
import { src, dest, series } from 'gulp';
import posthtml from 'posthtml';
import include from 'posthtml-include';
import modules from 'posthtml-modules';
<p>const html = () => {
return src('src/*.html')
.pipe(posthtml([
include({ root: 'src' }),
modules({ root: 'src', publicPath: './' })
]))
.pipe(dest('dist'));
};</p><p>export default series(html);</p>
关键点：
-
include支持<!-- @include file="header.html" -->类型的静态引入，root必须设为src才能正确解析相对路径 -
modules会自动把<link rel="stylesheet" href="css/index.css">中的href值转为带哈希的路径（需配合posthtml-assets插件），但默认不启用，这里仅用于路径规范化 - 若你用
publicPath: './'，所有资源路径将保持相对，避免部署到子目录时 404；若部署到根域，可改为'/'
PostHTML 插件链常见踩坑点
PostHTML 是声明式插件链，顺序决定行为。比如 posthtml-include 必须在 posthtml-modules 之前运行，否则被 include 进来的 HTML 片段里的 <script src="...>%20%E4%B8%8D%E4%BC%9A%E8%A2%AB%E6%A8%A1%E5%9D%97%E5%8C%96%E5%A4%84%E7%90%86%E3%80%82
%E5%85%B8%E5%9E%8B%E9%94%99%E8%AF%AF%E7%8E%B0%E8%B1%A1%EF%BC%9AUncaught%20TypeError:%20Cannot%20read%20property%20'xxx'%20of%20undefined%20%E6%88%96%E8%B5%84%E6%BA%90%20404%EF%BC%8C%E5%BE%80%E5%BE%80%E6%98%AF%E5%9B%A0%E4%B8%BA%EF%BC%9A
- %E6%8F%92%E4%BB%B6%E6%9C%AA%E6%AD%A3%E7%A1%AE%E5%AF%BC%E5%87%BA%E5%87%BD%E6%95%B0%EF%BC%88%E5%A6%82%E5%86%99%E6%88%90%20
posthtml([include()])%20%E5%8D%B4%E5%BF%98%E4%BA%86%20include%20%E6%98%AF%E4%B8%AA%E5%B7%A5%E5%8E%82%E5%87%BD%E6%95%B0%EF%BC%8C%E5%BF%85%E9%A1%BB%E8%B0%83%E7%94%A8%EF%BC%89 posthtml-modules%20%E7%9A%84%20root%20%E5%92%8C%E5%AE%9E%E9%99%85%E6%96%87%E4%BB%B6%E7%BB%93%E6%9E%84%E4%B8%8D%E4%B8%80%E8%87%B4%EF%BC%8C%E5%AF%BC%E8%87%B4%E5%AE%83%E6%89%BE%E4%B8%8D%E5%88%B0%20css/%20%E6%88%96%20js/%20%E7%9B%AE%E5%BD%95- %E7%94%A8%E4%BA%86%20
posthtml-assets%20%E4%BD%86%E6%B2%A1%E9%85%8D%20assets%20%E9%80%89%E9%A1%B9%EF%BC%8C%E7%BB%93%E6%9E%9C%20CSS/JS%20%E6%96%87%E4%BB%B6%E5%90%8D%E6%B2%A1%E5%8A%A0%E5%93%88%E5%B8%8C%EF%BC%8C%E7%BC%93%E5%AD%98%E5%A4%B1%E6%95%88 - PostHTML%20%E9%BB%98%E8%AE%A4%E4%B8%8D%E5%A4%84%E7%90%86%20
<img%20src=" ...></script>的路径，要额外加posthtml-img-autosize或手动写正则替换如何让打包后直接双击运行
不能直接双击打开
dist/index.html？99% 是因为路径写死了或用了fetch/XMLHttpRequest加载 JSON 数据——浏览器在file://协议下禁止跨文件读取，且相对路径解析规则和 HTTP 不同。解决办法只有两个：
- 改用
browser-sync启服务：npm install --save-dev browser-sync，然后在gulpfile.js加一个serve任务，server: { baseDir: 'dist' }，运行npx gulp serve就能访问http://localhost:3000 - 如果真要双击运行，必须确保：
<script></script>全部内联、所有src/href都是相对路径（如./js/app.js）、JSON 数据硬编码进 JS、禁用任何动态 import 或 fetch
PostHTML 可以帮你自动补全路径前缀，但无法绕过浏览器对
file://的限制——这点容易被忽略，直到上线前才发现 AJAX 请求全失败。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！ - 改用
