编译器具有高度模块化的多线程可插拔引擎架构。它将编排与计算任务解耦，以高效执行繁重的工作负载。

在零配置的 JavaScript 引擎和加速的 Rust 引擎之间进行选择。根据仓库大小、平台和性能需求选择引擎。

可用引擎

引擎 标识符 默认 目标用例 核心优势
JavaScript 引擎 "js" ✅ 是 标准网站、快速本地原型开发、可移植性。 在任何支持 Node.js 的设备上通用运行。
Rust 引擎（预览） "rust" ❌ 否 大型仓库（1,000+ 文件）、企业 CI/CD 构建。 通过 Tokio 最大化并行文件 I/O。

配置选项

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

{
  "title": "企业参考",
  "engine": "js",
  "src": "docs",
  "out": "site"
}

完整选项参考

键 支持的值 默认值 描述
engine "js"、"rust" "js" 处理文件发现和批量读取的执行层。

高级功能和限制

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

共享功能

  • 线程隔离：引擎在隔离的工作线程内安全地执行异步任务。这可防止阻塞主服务器循环。
  • 任务验证：严格的白名单防止未经授权的磁盘访问或未验证的执行模式。
  • 无缝互操作性：插件通过标准化接口（runWorkerTask）请求数据。它们不知道底层后端。

架构限制

  • 序列化开销：数据跨越原生运行时边界（N-API）。传递大型 JSON 对象的高度迭代任务会产生少量序列化损失。
  • 二进制兼容性：JavaScript 引擎在任何地方原生运行。Rust 引擎依赖于通过 npm 分发的特定于操作系统的平台二进制文件。

引擎加载器的工作原理

当 @docmd/core 启动时，内部加载器会检查你的活动配置：

  1. 解析：如果配置为 "rust"，引擎会延迟加载特定于架构的原生包（例如 @docmd/engine-rust-darwin-arm64）。
  2. 优雅降级：如果二进制文件缺失或不受支持，引擎会记录一条建议通知。然后它会透明地降级到 JavaScript 引擎。你的构建始终会成功。

探索每个引擎的深入文档：

next 概览