配合PostHTML插件进行HTML代码自动转换与优化实践-html教程-PHP中文网

posthtml插件必须显式传入posthtml([])数组才生效，否则被忽略；常见错误是漏写方括号或未按顺序配置（如posthtml-include须在posthtml-minifier前），且需正确设置root、extensions等选项避免路径解析失败。

配合posthtml插件进行html代码自动转换与优化实践

PostHTML 插件怎么加载才不会被忽略

PostHTML 默认不自动执行插件，posthtml() 调用时必须显式传入插件数组，否则所有配置形同虚设。常见错误是只写了插件导入却没放进 plugins 选项里，或者误把插件函数直接当参数传（漏了 []）。

正确写法：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，不是相对于被包含文件的位置。很多项目结构嵌套深，一写 <include src="header.html"></include> 就报 ENOTDIR 或 ENOENT。

解决方法：显式传入 root 选项，比如 { root: path.resolve(__dirname, 'src') }
相对路径要小心：src="../components/footer.html" 是相对于调用 <include></include> 的文件所在目录，不是 root
别依赖默认扩展名：如果包含的是 .htm 或无后缀文件，得加 extensions: ['.html', '.htm']

minifier 压缩后 JS/CSS 失效怎么办

posthtml-minifier 默认启用 collapseWhitespace 和 removeComments，但某些内联 <script></script> 或 <style></style> 里有依赖空白或注释的逻辑（比如 CSS hack、模板字符串换行），会被破坏。

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。

下载

临时禁用某类压缩：{ collapseWhitespace: false, removeComments: false }
更稳妥的做法：用 posthtml-expressions 或 posthtml-modules 把逻辑外移，避免压缩干扰
注意 posthtml-minifier 不处理外部资源，JS/CSS 文件需单独走 Webpack/Vite 构建流程，别指望它替你压缩 <script src="app.js"></script>

如何让自定义插件支持异步操作

PostHTML 插件默认是同步的，但读取远程模板、调用 API、解析 YAML Front Matter 等场景需要异步。直接 return Promise 不生效，必须用 async/await + 正确的插件签名。

插件函数必须返回一个对象，且 async 函数要包裹在 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()) 看是否卡住