docmd 0.7.5 版本将安全修复与重大 i18n 优化相结合。它消除了 Mermaid 插件中的上游 uuid 漏洞，为语言切换器添加了多层保护机制，并引入了构建时页面清单，用即时本地查找替代所有运行时网络检查。
🛡️ 安全更新
Mermaid 插件 — 依赖树修复
@docmd/plugin-mermaid 包此前将 mermaid 声明为生产环境 dependency。这导致存在漏洞的传递性子依赖 uuid@<14.0.0 被安装到每个使用者的 node_modules 中，尽管该包在运行时从未使用它。
根本原因：Mermaid 库在运行时仅通过 CDN 在浏览器中加载。npm 上的 mermaid 包仅在开发过程中用于 TypeScript 类型检查和 esbuild 打包步骤。它被错误地归类为生产依赖。
修复方案：mermaid 已从 @docmd/plugin-mermaid 的 dependencies 移至 devDependencies。发布的包现在具有零生产依赖，因此 mermaid 及其存在漏洞的 uuid 子依赖不会为最终用户安装。
npm audit/pnpm audit现在对使用@docmd/plugin-mermaid的项目报告 0 个漏洞。- 无功能变更 — Mermaid 渲染流程完全不受影响。
🌐 i18n — 语言切换安全机制
此前，如果在 i18n.locales 中声明了某个语言区域，但其源目录（如 docs/hi/）不存在，语言切换器仍会将其显示为可点击状态 — 选择后会导致 404 错误。
修复方案：引擎现在在构建时预扫描语言区域目录。没有源目录的语言区域会在语言切换器中自动显示为禁用状态，带有 N/A 标记、aria-disabled 属性，且不可点击。
- 构建时检测：引擎在渲染任何页面之前检查哪些语言区域目录实际存在。
- 模板级禁用：不可用的语言区域显示为灰色，带有"N/A"标记和
href="#"。 - 客户端保护：点击已禁用的语言区域不会执行任何操作 — 无导航、无 404。
- 链式回退：如果某个语言区域可用但特定页面缺失，引擎会回退到默认语言版本的页面，并显示本地化的警告提示。
⚡ i18n — 构建时页面清单
此前，语言切换器使用 fetch(url, { method: 'HEAD' }) 来验证目标语言区域中是否存在某个页面。这增加了延迟，在某些 CDN 上无法正常工作，且离线时完全失效。
修复方案：引擎现在在构建时生成一个页面清单 — 一个微小的 JS 文件（docmd-i18n-manifest.js），将每个语言区域映射到其可用的页面路径。客户端切换器同步读取此清单。
- 零网络请求：页面存在性从清单本地检查 — 无 HEAD 请求。
- 离线可用：清单与站点资产一起打包。
- CDN 无关：不依赖托管提供商如何处理 HEAD 请求。
- 优雅降级：如果清单加载失败，切换器会自动回退到 HEAD 请求。
启用 i18n 时，每个语言区域必须在源目录下拥有自己的子目录（如 docs/en/、docs/hi/）。默认语言的目录是部分翻译语言区域的回退源，必须存在。
i18n 安全机制 — docmd 对比
| 能力 | docmd | VitePress | Docusaurus | Starlight |
|---|---|---|---|---|
| 逐页回退到默认语言 | ✅ | ❌ (404) | ❌ (404) | ✅ |
| 本地化"未翻译"警告 | ✅ | ❌ | ❌ | ✅ |
| 自动禁用缺失语言区域 | ✅ | ❌ | ❌ | ❌ |
| 客户端导航保护 | ✅ | ❌ | ❌ | ❌ |
| 版本控制 + i18n 组合 | ✅ | ❌ | ❌ | ❌ |
| 旧版本向后兼容（无语言区域目录） | ✅ | N/A | N/A | N/A |
| RTL 方向支持 | ✅ | ✅ | ✅ | ✅ |
| 零配置（无需自定义 React/Vue） | ✅ | 部分 | ❌ | ✅ |
VitePress 和 Docusaurus 在非默认语言区域缺少页面时都会返回 404 错误 — 需要手动配置服务器端重定向或自定义组件来优雅处理。Starlight (Astro) 提供逐页回退和翻译提示，与 docmd 类似 — 但不会自动禁用缺失的语言区域目录，也不会防止客户端导航到不存在的语言区域。
迁移指南
对于最终用户：使用 npm update @docmd/plugin-mermaid 或 pnpm update @docmd/plugin-mermaid 更新到最新的补丁版本。无需任何配置更改。