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。然而这一操作对内联的 ）它并不处理，这部分应交给 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 或外部变量缓存。而这一步，往往是调试时最难定位的问题根源。