单文件 HTML 工具为何比框架更适合做小工具：140 倍体积差与四个会咬人的坑

单文件 HTML 在小工具场景能压过框架，原因不是"轻"，而是它的源码和交付物是同一个文件——这一个事实同时消掉了构建、依赖、部署三层成本。下面用一次可复现的对照实验说明它到底省在哪里，以及它在哪些地方会反噬。

同一功能的两个实现

需求定死：输入 Unix 时间戳，输出本地时间。先写 React 版本。

import React, { useState } from "react";
import { createRoot } from "react-dom/client";

function Tool() {
  const [v, setV] = useState("1700000000");
  const n = Number(v);
  const out = v.trim() !== "" && Number.isFinite(n)
    ? new Date(n * 1000).toLocaleString("zh-CN", { hour12: false })
    : "无效输入";
  return React.createElement("div", null,
    React.createElement("input", { value: v, onChange: e => setV(e.target.value) }),
    React.createElement("p", null, out)
  );
}
createRoot(document.getElementById("root")).render(React.createElement(Tool));

打包命令（esbuild 22.x，react@18）：

esbuild app.jsx --bundle --minify --format=iife \
  --define:process.env.NODE_ENV='"production"' --outfile=bundle.js

同样的功能用原生实现，整份 HTML 只有 1 KB：

<input id="ts" value="1700000000" inputmode="numeric">
<p id="out"></p>
<script>
  var ts = document.getElementById("ts"), out = document.getElementById("out");
  function render() {
    var n = Number(ts.value);
    out.textContent = ts.value.trim() !== "" && Number.isFinite(n)
      ? new Date(n * 1000).toLocaleString("zh-CN", { hour12: false })
      : "无效输入";
  }
  ts.addEventListener("input", render);
  render();
</script>

实测结果（gzip 为 level 9）：

差距 140.8 倍，gzip 后仍有 69.6 倍。142 KB 里业务代码不到 1 KB，剩下全是运行时：react + react-dom + scheduler 三件套，其中 reconciler 和事件合成系统在 Hello World 里一行都没被用到。

这 140 倍在真实项目里意味着什么

我把本机 WorkBuddy-Taskflow 目录下全部 27 个单文件 HTML 扫了一遍（os.walk + 正则统计）：

• 体积中位数 31,848 B，gzip 后 11,120 B
• 外部 CSS 引用 0 个，外部 JS 引用 1 个（一个浏览器扩展的 popup.html，属特例）
• 缺失 <meta charset> 的 0 个
• 内含超过 800 B 内联逻辑的只有 3 个

这组数字说了两件不太好听的事。好消息是"零外部请求"在单文件模式下确实能稳定做到；坏消息是绝大多数单文件产物其实是静态报告，不是工具。真正带交互逻辑的只有 3 个。也就是说，单文件模式擅长的是读多写少、一次生成多次查看的东西，而不是所有"小工具"。

还有一个细节值得注意：这 27 个文件的文件名全部带日期后缀，从 9 月中旬排到 10 月中旬。版本管理实际上是靠命名完成的——改一版就存一个新文件，旧文件不删。这种"看起来很不工程"的做法在单文件场景下反而有效，因为一个 30 KB 的文件重命名成本接近于零，而在 Git 里为一个只活两周的报告开分支是纯浪费。单文件把版本控制的粒度从"提交"降到了"文件"，这是它能长期不装构建链还活得不错的原因之一。

体积之外的第一笔账：依赖链

清空 npm 缓存后模拟断网安装：

npm error code ENOTCACHED
npm error request to https://registry.npmjs.org/react failed:
cache mode is 'only-if-cached' but no cached response is available.

框架方案在离线机器上连编译都过不去。这不是性能差异，是可用性差异：单文件 HTML 在断网、临时机器、别人的电脑上双击就能改、就能用。

更长远的一笔账是依赖腐烂。三年后再打开一个单文件 HTML，它照样跑；三年后再 npm i 一份 2023 年的 lockfile，面对的是 Node 版本、peer 依赖、registry 迁移三个故障的叠加，而那时你已经不记得当初为什么把版本锁在那里。

第二笔账：部署

单文件工具的发布动作是"把文件发出去"。微信、邮件附件、论坛正文里的一个链接，甚至 file:// 直接打开。框架产物要先跑构建、再上传 dist、再配 CDN 缓存策略，改一行要重走一遍。对于一天改三次的内部小工具，这条链路的摩擦成本远高于那 140 KB。

回滚也是同一个逻辑。单文件的回滚就是"把昨天那个文件再发一次"，动作是复制，耗时以秒计；框架产物的回滚要走 revert、重跑 CI、等 CDN 刷新，还得确认构建环境能复现出昨天那版。故障发生时，能不能在三十秒内退回上一个可用状态，比首屏少 40 KB 重要得多。

四个会咬人的坑

一、缺 charset，中文变乱码

27 个文件里一个都没缺，不是巧合——这个坑踩过一次就会写进模板。<meta charset="UTF-8"> 必须出现在文档前 1024 字节内。

同一类问题在命令行侧也存在。PowerShell 读同一份 UTF-8 文件，Get-Content 不加 -Encoding UTF8 会按系统 ANSI 代码页解码，中文直接变成问号。文件本身没问题，读取路径错了。

二、字符串里的 </script> 会截断整个脚本

我用 html.parser 模拟解析器处理下面这行：

const raw = "</script>"; console.log("这句永远不会执行");

解析到的 script 文本只有 13 字节，内容是 const raw = "，后面的代码全部被吞掉。这是 HTML 分词器的行为：script 内部不认 JavaScript 语法，只认 </script 这个字符序列。

修复方式二选一：

const raw = "<\/script>";                    // 转义斜杠
const raw = JSON.stringify(s).replace(/</g, "\\u003c");  // 兜底所有 <

把 JSON 数据内联进单文件时，第二种做法必须用。JSON.stringify 默认不转义 <，一条包含闭合标签的用户评论就能让整个脚本失效。

三、file:// 下剪贴板 API 直接不存在

navigator.clipboard.writeText() 只在安全上下文（https 或 localhost）可用。双击打开的页面里 navigator.clipboard 是 undefined，直接调用会抛 TypeError: Cannot read properties of undefined。降级路径：

function copy(text) {
  if (navigator.clipboard && window.isSecureContext) {
    return navigator.clipboard.writeText(text);
  }
  var ta = document.createElement("textarea");
  ta.value = text;
  ta.style.position = "fixed";
  ta.style.opacity = "0";
  document.body.appendChild(ta);
  ta.select();
  var ok = document.execCommand("copy");
  ta.remove();
  return ok ? Promise.resolve() : Promise.reject(new Error("copy failed"));
}

execCommand 已标记废弃，但它是 file:// 下唯一还能用的路径，短期内不会真的移除。

四、innerHTML 重建列表，监听器跟着旧节点一起消失

单文件工具的典型写法是 list.innerHTML = rows.join("")。DOM 被整体替换后，绑在旧节点上的 addEventListener 全部失效，表现是"点按钮没反应"，而控制台没有任何报错。正确做法是事件委托：

list.addEventListener("click", function (e) {
  var btn = e.target.closest("[data-id]");
  if (!btn) return;
  handle(btn.dataset.id);
});

监听器挂在容器上，子节点怎么重建都不影响。

什么情况下该交回框架

四种情况，单文件模式会明显吃力：

需要测试覆盖。 没有模块边界，函数全在全局作用域里，写单测要先造 DOM 环境。

多人同时改。 一个 3000 行的 HTML 文件，两个人在不同分支改同一段，冲突几乎必然。

状态要跨设备同步。 单文件本质是无状态交付物，一旦要登录、要云端存储，就得引入后端，那时构建链路的价值开始显现。

需要持续接收依赖安全补丁。 内联的第三方库没有升级通道，只能整份替换。

结论

选型判据不是代码量，而是这个产物要不要活过它的作者：只服务一次决策、一次查看、一次分享的东西，单文件是成本最低的形态；要长期迭代、多人协作、持续打补丁的东西，那 140 倍体积就是应该付的钱。真正贵的从来不是 142 KB，而是替 1 KB 的逻辑维护一整套构建与依赖链。