PostHTML插件：HTML代码自动转换与优化实践

PostHTML 本身只是一个轻量的 HTML 处理管道的“骨架”——如果没有安装插件，它基本上只能输出原样。很多开发者第一次使用时，会遇到配置工整但运行后毫无反应的情况。核心原因其实很简单：插件需要被显式声明。

PostHTML 插件为什么加载了却没效果？

PostHTML 默认不会自动执行任何插件。你必须把所需插件放在一个数组里，并传给 posthtml() 函数。否则，即便已经用 require 引入了插件包，一切也是徒劳。 - **正确写法**：posthtml([require('posthtml-include'), require('posthtml-minifier')]) - **典型翻车写法**：漏掉数组方括号，直接丢进一个函数：posthtml(require('posthtml-include'))，这会触发一个经典错误——TypeError: plugin is not a function。 - **顺序有时候比内容还重要**：比如 posthtml-include 必须排在 posthtml-minifier 前面。如果先压缩再 include，那些待展开的 标签还没碰到内容就被压缩器“修剪”掉了，路径必然失效。

include 路径解析失败的深层原因

很多人在遇到 posthtml-include 报错时，第一反应是路径写错了。但冷静下来，有一个容易忽视的默认行为：它默认基于当前工作目录去解析 src 路径，而不是基于被包含文件所在的目录。如果你的项目结构嵌套较深，直接写 ，大概率会弹出 ENOTDIR 或 ENOENT 错误。 解决办法很直接： - 显式传入 root 选项，比如 { root: path.resolve(__dirname, 'src') }，把解析的根目录固定。 - 注意相对路径的复杂性：src="../components/footer.html" 这个写法，它的参考点是发起 的 HTML 文件所在的目录，而不是你设定的 root。 - 文件扩展名也是个陷阱。默认只认 .html，如果包含的是 .htm 或没有后缀的文件，需要通过 extensions: ['.html', '.htm'] 显式声明。

minifier 压缩完，JS 和 CSS 怎么全崩了？

posthtml-minifier 默认开启了 collapseWhitespace 和 removeComments。但这对内联的 或 来说，有时是毁灭性的。尤其是那些依赖空白行或特殊注释的 CSS hack，以及模板字符串中的换行逻辑，很容易被它一刀切掉。 这里有两个比较稳妥的应对策略： - **局部妥协**：如果只需要短期压制，可以临时关闭某些压缩选项，比如 { collapseWhitespace: false, removeComments: false }。虽然不完美，但能保住内联逻辑不被破坏。 - **结构优化**：更推荐的做法是，把依赖空白或注释的逻辑外移到独立的模块中。例如通过 posthtml-expressions 或 posthtml-modules 来隔离，让压缩器只管压缩纯 HTML 结构，不触碰业务逻辑。 - 需要明确一点：posthtml-minifier 只处理 HTML 内部的压缩，外部引用的 JS 或 CSS 文件（比如 ）它不处理，需要交给 Webpack 或 Vite 去处理，别指望它替你优化文件内容。

自定义插件怎么让它支持异步操作？

PostHTML 插件默认是纯同步的，但现实场景中，读取远程模板、调用 API、解析 YAML Front Matter 这些操作都离不开异步。很多新手直接返回一个 Promise，发现完全不起作用。关键在于，插件需要正确的签名和 async/await 配合。 - 插件函数必须返回一个对象，并且如果要用异步，需要包裹在 tree 回调里。一个正确的写法是：module.exports = async (tree) => { const data = await fetch(...); tree.match({ tag: 'blog' }, ...); } - 一个容易踩的坑：在插件里直接 await 后修改 tree，却不调用 tree.match 或 tree.walk。PostHTML 不会等待你的 Promise，所以你的修改根本不会被应用。 - 调试建议：在插件开头加一句 console.log('running') 确认它是否被调用了；然后加一段 console.log(await someAsync()) 看看是不是卡在异步步骤上。 PostHTML 的链式处理很轻量，但每个插件的执行时机和上下文边界很容易让人产生错觉。最容易被忽略的一点是：插件之间不共享状态——tree 是一个只读副本。想跨插件传递数据，得靠 tree.metadata 或外部变量缓存。而这一步，往往是调试时最难定位的问题根源。