PostHTML插件必须显式传入posthtml([])数组才生效，否则被忽略；常见错误是漏写方括号或未按顺序配置（如posthtml-include须在posthtml-minifier前），且需正确设置root、extensions等选项避免路径解析失败。
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>的文件所在目录，不是root - 别依赖默认扩展名：如果包含的是
.htm或无后缀文件，得加extensions: ['.html', '.htm']
minifier 压缩后 JS/CSS 失效怎么办
posthtml-minifier 默认启用 collapseWhitespace 和 removeComments，但某些内联 <script> 或 <style> 里有依赖空白或注释的逻辑（比如 CSS hack、模板字符串换行），会被破坏。
Article To Html
下载
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
- 临时禁用某类压缩：
{ 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())看是否卡住
PostHTML 的链式处理很轻量，但每个插件的执行时机和上下文边界容易模糊。最常被忽略的是：插件之间不共享状态，tree 是只读副本，想跨插件传数据得靠 tree.metadata 或外部变量缓存 —— 而这恰恰是调试时最难定位的问题来源。
