Gulp 在 HTML 项目中非必须但实用，关键在于任务路径与真实文件流匹配；常见失败源于 gulp.src/gulp.dest 路径错误、HTML 压缩破坏空格、browser-sync 被拦截或监听范围过窄、Gulp 4 语法不兼容等问题。
直接上结论：Gulp 在 HTML 项目中不是“必须”，但只要项目里有 src/*.html、src/css/、src/js/ 这类源文件结构，且你希望压缩、注入、自动刷新或避免手动复制文件，Gulp 就能立刻见效——关键不在“用不用”，而在“任务定义是否匹配真实文件流”。
gulp.src 和 gulp.dest 路径写错是最常见的构建失败原因
很多新手跑不通任务，不是插件没装，而是路径和实际目录对不上。Gulp 不会报“找不到 src 文件夹”这种友好提示，它只会静默跳过或抛出 Error: No files matching。
-
gulp.src('src/**/*.html')匹配src/下所有层级的 HTML，但如果你的文件在app/index.html，就得写成gulp.src('app/**/*.html') -
gulp.dest('dist')是相对当前工作目录（即package.json所在位置）写入，不是相对于gulpfile.js；如果输出后发现dist里空空如也，先ls -la确认当前命令行所在路径 - Windows 用户注意反斜杠：
gulp.src('src\*.html')或统一用正斜杠gulp.src('src/*.html')，Node.js 通常能自动转换，但某些插件（如gulp-rev）对路径敏感
HTML 压缩任务里 collapseWhitespace 导致页面错位
用 gulp-htmlmin 压缩时，collapseWhitespace: true 会删掉所有换行和多余空格——这在纯静态页没问题，但一旦 HTML 里有 inline 元素靠空格分隔（比如 <span>A</span> <span>B</span>），压缩后变成 <span>A</span><span>B</span>，可能破坏样式。
- 安全做法是只开基础压缩：
{ removeComments: true, collapseBooleanAttributes: true, removeEmptyAttributes: true } - 若必须压缩空白，加
conservativeCollapse: true，它会保留标签间至少一个空格 - 模板类 HTML（含
<%= name %>或{{title}}）不能直接丢给htmlmin，得先用gulp-consolidate或gulp-file-include渲染完再压缩
browser-sync 实时刷新不生效？检查 livereload 是否被拦截
gulp-connect 和 browser-sync 都能起服务，但后者更主流。常见失效场景不是代码写错，而是环境干扰：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- Chrome 浏览器开了 “禁用 JavaScript” 或安装了广告屏蔽插件（如 uBlock Origin），会拦截
browser-sync注入的script标签 - 本地开了代理（如 Charles/Fiddler），默认会拦截 WebSocket 连接，关掉或配置 bypass localhost
- 任务里写了
browserSync.init({ server: 'dist' })，但 HTML 中引用的 JS/CSS 路径仍是src/开头，浏览器 404 了自然不会触发 reload - 监听范围太窄：
gulp.watch('src/*.html').on('change', browserSync.reload)只监听根目录 HTML，漏掉src/pages/*.html，应改用gulp.watch(['src/**/*.html', 'dist/**/*']).on('change', browserSync.reload)
Gulp 4 的 task 写法和 v3 完全不兼容
现在 npm 默认装的是 Gulp 4，但网上大量教程还是 v3 的 gulp.task('build', ['html', 'css']) 写法，直接复制会报 TypeError: task is not a function。
- v4 必须导出函数：
const htmlTask = () => gulp.src('src/*.html').pipe(...).pipe(gulp.dest('dist'));，然后exports.html = htmlTask; - 串行执行用
series()：exports.build = series(htmlTask, cssTask, jsTask); - 并行执行用
parallel()：exports.dev = parallel(htmlTask, watchTask); - 别再用
gulp.run()或run-sequence插件，它们在 v4 中已废弃
真正卡住人的往往不是某一行代码，而是 src 和 dest 的路径映射、插件之间的数据流断点、或者浏览器缓存和 livereload 的竞态——建议每次新增一个任务，先用 console.log 打印 file.path 确认流进来的是什么，再决定 pipe 哪个插件。
