✨ 重点

本版本专注于整合离线链接生成、保障依赖安装的安全性，以及优化测试执行。已解决的关键问题包括 #179（离线文件夹导航重定向）、#167/#175（离线构建中的 SEO 元数据缺失），以及针对安装器中命令注入的安全加固（CWE-78）。

此外，我们还解决了测试运行器中的性能瓶颈，将测试套件延迟从 15 分钟降至 2 分钟以内。

无破坏性变更。无需新配置。现有配置、插件和 CI 流水线均可正常工作。

🐛 修复：统一离线导航 (#179)

此前，系统生成的导航元素（Logo、面包屑、版本/语言切换器、侧边栏）会输出目录式链接（如 ./ 或 /）。在 file:// 下离线查看时，浏览器会将这些链接解析为文件系统目录路径，而非显式 HTML 文件，导致目录列表或页面损坏。

修复方案： 所有 URL 生成已整合到单一事实来源（packages/parser/src/utils/url-utils.ts）。导航组件现在通过绑定的辅助函数（buildRelativeUrl 和 buildAbsoluteUrl）路由。在 --offline 模式下，所有生成的 URL 会自动将目录端点解析为显式的 index.html 目标（如 ./index.html 或 ../index.html），确保跨本地文件系统的导航万无一失。

🧹 SEO 与元数据稳健性 (#167, #175, #177)

Canonical 链接、Open Graph 标签（og:url、og:image）和 Twitter Card 标签需要绝对 URL。当 siteUrl 缺失或项目在 --offline 模式下编译时，这些标签会解析为损坏的根相对路径（如 /guide/），导致元数据错误。

修复方案： SEO 插件现在会检查 siteUrl 和 offline 标志。在离线构建或未配置 siteUrl 时，Canonical 和 Og/Twitter 元数据标签会被省略，除非它们是显式的绝对 URL。

🔒 安全：命令生成加固 (CWE-78)

@docmd/plugin-search 中的对等依赖安装已重构，以防止命令注入风险。

修复方案： 我们用安全的集中化运行时依赖安装器替换了基于 Shell 的执行（execSync）。包管理器现在通过参数数组直接生成，不经过 Shell 展开，确保在 CI 和生产环境中跨平台稳健执行。

⚡ 优化：测试套件依赖解析

功能集成和资产管线测试此前会在临时测试文件夹中触发高成本、网络密集的包安装（例如下载 docmd-search 及其对等依赖），使执行时间高达 15 分钟。

修复方案： 我们引入了 DOCMD_TEST_SEARCH_PATH 环境变量。测试运行期间，插件绕过外部 npm 包下载，直接从 monorepo 工作区解析搜索和模板依赖。整个测试套件现在在 2 分钟内完成。

🚀 优化：增量语义索引缓存复用

此前，搜索插件在每次重建/重载时从头编译搜索索引，耗时 30-42 秒，因为输出目录（site/.docmd-search/）会被清除。

修复方案：

  • 搜索插件现在将语义索引写入文档源目录（docs/.docmd-search/ 或版本目录 ver.dir/.docmd-search/），该目录在构建间保留并提交到版本控制。
  • 它在此文件夹中运行增量索引（复用现有清单和批次文件），并将最终生成的索引资产递归复制到站点输出目录。
  • 这带来了 100 倍以上的构建加速（热重建在 300ms 内完成）。

⚙️ Rust 引擎原生插件 DX 与路由

  • 本地二进制复制： 在 @docmd/engine-rust 中配置了 postinstall.cjs，检查同级的 rust-binaries/bin/ 文件夹，使 Rust 引擎可在 npm CDN 发布前用于新版本的开发和测试。
  • 任务路由： 更新了任务路由，仅将原生支持的任务（file:* 和 search:index）分派给 Rust 引擎，对不支持的任务无缝回退到 JS。

迁移

无需迁移。现有配置、插件和 CI 流水线均可正常工作。

完整变更日志：https://github.com/docmd-io/docmd/compare/0.8.13...0.8.14

下一页 概览