故障排查

环境或 Typst 版本不匹配

先检查 Node、pnpm、Typst 和 pdffonts。Typst 必须为 0.15.0，HTML 实验接口升级需要完整兼容测试，不应临时跳过版本检查。PDF 字体缺失时安装指南要求的 CJK 和等宽字体，再重新构建。

找不到内容索引

使用根目录 inkstack dev 或 inkstack build，让项目保证 Typst 编译和资源同步顺序。直接调用 Astro 不会创建隔离预览索引。纯单元检查可运行 inkstack check，完整 Astro 检查应在有有效产物的环境中运行。

导入失败或图片缺失

先用 --dry-run 查看资源解析。确认资源存在、路径编码正确、大小未超限，且 realpath 位于允许根。需要更大的资源范围时明确传入 --resource-root，不要删除路径检查。

Typst 动态路径、自定义函数与环依赖不在自动导入范围；人工迁移后真实编译。HTTPS 外链不自动离线化，远程失效应保存本地资源并重新导入。

Markdown 或 MDX 被拒绝

检查元数据是否含未知字段，正文是否超出 h2–h4。普通 Markdown 不支持 raw HTML；需要组件时使用经过审查的 MDX，而不是关闭 sanitizer。

MDX 保留 named exports 不得覆盖 front matter；组件只从本地源码或已安装 workspace 包导入，不从网络动态加载构建代码。

搜索没有结果

搜索只在完整 build 后可用。运行 inkstack preview，开发模式不会复用旧索引。文章搜索与文档搜索是不同索引；你在文档页面检索时不会返回博客文章。

草稿、unlisted、private 和 archived 不进入文章搜索。如果刚部署的新内容没有出现，确认部署摘要是最新版本，并核对 Pagefind 的重验证响应头，不要只替换部分索引文件。

文档导航或链接失败

文件名须为小写连字符，首页为 overview.md；同组 order 不能重复。手册链接使用同目录 .md 文件和有效锚点，不链接内部工程记录。检查构建 base、canonical 和目标页是否同时存在。

构建锁与所有权报错

先确认对应构建是否仍活跃；不要递归清理整个仓库。只有确认进程已结束、目标确为该构建的生成锁后才处理明确报错的锁文件。未知所有权目录应先调查内容，不能直接覆盖。

浏览器测试与部署摘要不一致

inkstack build
pnpm verify:report
pnpm test:e2e

验收服务器使用独立 4328 端口并拒绝复用旧进程。不要停止日常开发服务器，也不要只替换 HTML 或搜索目录。浏览器与部署必须消费同名 artifact。

固定 Linux 容器环境失败时先处理容器用户、浏览器启动和字体问题，不以跳过 Firefox 或放宽截图容差代替修正。任何门禁失败时停止上传；线上应保留上一份可用版本。