HTML 文件压缩实践指南

单文件压缩#

1
html-minifier-terser index.html -o index.min.html --collapse-whitespace --remove-comments --minify-css true --minify-js true

批量处理目录#

1
html-minifier-terser --input-dir . --output-dir ./dist --file-ext html --collapse-whitespace --remove-comments --remove-redundant-attributes --minify-css true --minify-js true

--input-dir 与 --output-dir 会递归处理目录下所有 .html 文件，并保持原有目录结构输出到目标位置。注意这里的 --minify-css/--minify-js 只压缩 HTML 内联的 <style>/<script> 和 style="" 属性，不会处理外部引用的 .css/.js 文件，这部分需要单独压缩（见下文）。

⚠️ 排除 dist 目录，避免循环生成#

html-minifier-terser 的 --input-dir 是递归扫描的，且没有提供 --exclude 之类的参数来排除子目录。这意味着：如果 --output-dir 指向的 dist 恰好在 --input-dir 扫描范围内（比如两者同级于一个更外层目录、或者 dist 直接是当前目录的子目录且你重复执行了命令），第二次运行时上一次生成的 dist/*.html 会被当成输入重新压缩一遍，输出到 dist/dist/*.html，如此反复，目录越跑越深，也可能拖慢甚至卡死命令。

常用参数说明#

跨文件引用：压缩后别忘了同步路径#

这是多文件静态站点压缩时最容易踩的坑：上述工具都只压缩各自负责的文件类型，不会互相感知。具体来说：

• html-minifier-terser 不会修改 HTML 里 <link href="style.css"> 或 <script src="common.js"> 的路径，哪怕你把压缩后的 CSS/JS 存成了 style.min.css、common.min.js
• 如果压缩后文件改了名（加了 .min 后缀）而 HTML 里的引用没同步修改，线上加载的仍然是没压缩过的原文件，压缩等于白做

两种规避方式：

1. 保持文件名不变，只改输出目录（推荐，零额外工作量）：把压缩后的 CSS/JS 输出到与源文件相同的文件名，比如 dist/style.css（而不是 dist/style.min.css）。只要 HTML 里写的是相对路径 href="style.css"，把整个 dist/ 目录部署上线时引用就天然正确，不需要改动 HTML 一个字。
2. 改名 + 手动/脚本同步引用：如果需要保留 .min 后缀（比如为了和未压缩版本共存、方便调试对比），就需要额外一步查找替换 HTML 中的 href/src，或者改用支持自动重写引用的构建工具（如 Vite）。

对于没有构建工具的纯静态目录，方式一通常是最省心的选择。

Node.js API 调用#

1
const { minify } = require("html-minifier-terser");
2
const fs = require("fs");
3

4
const html = fs.readFileSync("index.html", "utf8");
5

6
minify(html, {
7
  collapseWhitespace: true,
8
  removeComments: true,
9
  removeRedundantAttributes: true,
10
  minifyCSS: true,
11
  minifyJS: true,
12
}).then((result) => {
13
  fs.writeFileSync("index.min.html", result);
14
});

clean-css-cli#

1
# 单文件
2
cleancss -o style.min.css style.css
3

4
# 批量（shell 通配符）
5
cleancss -o dist/style.min.css src/*.css

lightningcss#

1
lightningcss --minify --output-file style.min.css style.css

lightningcss 处理速度更快，并且能做语法层面的浏览器兼容降级；如果项目对构建速度敏感，或者需要精细控制目标浏览器范围，优先考虑它。

terser#

1
# 单文件
2
terser common.js -o common.min.js --compress --mangle
3

4
# 批量（需要配合 shell 循环）
5
for f in src/*.js; do
6
  terser "$f" -o "dist/$(basename "$f" .js).min.js" --compress --mangle
7
done

--mangle 会重命名局部变量（比如 let userName 变成 let a），压缩率显著提升，但如果代码里有依赖具体变量名的逻辑（比如某些框架的全局注入、动态 eval/字符串拼接访问变量），需要格外小心测试。只做无重命名的压缩，去掉 --mangle 更保守安全。

常用参数说明#