编译器拥有一套高度模块化、多线程的 可插拔引擎架构 (Pluggable Engine Architecture)。它把"调度"与"计算"解耦，从而高效执行繁重任务。

您可以在零配置的 JavaScript 引擎 与更快的 Rust 引擎 之间选择。请根据仓库规模、平台与性能需求做出取舍。

可用引擎

引擎 标识符 默认 目标场景 关键优势
JavaScript 引擎 "js" ✅ 是 标准站点、本地快速原型、跨平台可移植性。 只要运行时支持 Node.js，便可在任意设备运行。
Rust 引擎 (预览) "rust" ❌ 否 巨型仓库（1000+ 文件）、企业级 CI/CD 构建。 通过 Tokio 最大化并行的文件 I/O。

配置项

在 docmd.config.json 中配置构建引擎。直接设置 engine 参数即可。

docmd.config.json
{
  "title": "企业参考手册",
  "engine": "js",
  "src": "docs",
  "out": "site"
}

完整选项参考

键 支持值 默认 说明
engine "js", "rust" "js" 负责文件发现与批量读取的执行层。

高层能力与限制

两种引擎共享一套严格的执行边界。核心 API 层强制统一的安全性与确定性输出。

共有能力

  • 线程隔离：引擎在隔离的 Worker 线程中安全执行异步任务，避免阻塞主服务器循环。
  • 任务校验：严格的 allowlist 阻止未授权的磁盘访问或不可信的执行模式。
  • 无缝互通：插件通过标准化接口 (runWorkerTask) 获取数据，无需关心底层后端。

架构限制

  • 序列化开销：数据需要跨越原生运行时边界（N-API）。对高度迭代、传大数据 JSON 的任务，会有少量序列化代价。
  • 二进制兼容性：JavaScript 引擎在任何平台都能直接运行；Rust 引擎依赖通过 npm 分发的、与操作系统对应的原生二进制。

引擎加载器的工作机制

@docmd/core 启动时，内部加载器会读取您的当前配置：

  1. 解析：若配置为 "rust"，引擎会惰性加载对应架构的原生包（例如 @docmd/engine-rust-darwin-arm64）。
  2. 优雅回退：若二进制缺失或不受支持，引擎会打印一条非致命通知，并自动回退到 JavaScript 引擎 —— 您的构建仍然能顺利完成。

深入了解各引擎：

previous Setup next JavaScript 引擎