问题

随着软件产品的演进，企业用户往往仍在使用较旧的 LTS（长期支持）版本。在发布 v2 时直接放弃 v1 的文档会让这些用户陷入困境，而为每个版本维护完全独立的网站则会导致用户体验支离破碎并分散 SEO 权重。

为什么重要

如果没有一种无缝切换版本的方式，开发者往往会错误地将最新文档中的指令应用到旧版本环境中，从而导致错误并增加支持成本。统一的版本控制系统可确保用户始终了解自己所处的上下文，并能轻松地在同一页面的不同版本之间跳转。

方法

docmd 具有原生的 版本控制引擎，将版本视为一等公民。它将构建结果隔离到以版本为前缀的目录中，提供“粘性切换 (Sticky Switching)”机制来保留当前页面路径，并将搜索结果准确限制在当前版本上下文中。

实施

1. 组织源目录

将最新的文档保留在标准目录中（例如 docs/），并将旧版本放在同级目录中（例如 docs-v1/）。

my-project/
├── docs/             # v2.x (当前版本)
├── docs-v1/          # v1.x (旧版 LTS)
└── docmd.config.js

2. 配置版本映射

在 docmd.config.js 中定义您的版本结构。current（当前）版本在根 URL 处提供服务，其他版本在 /{id}/ 处提供服务。

// docmd.config.js
export default {
  versions: {
    current: 'v2',           // 在 / 处提供服务
    position: 'sidebar-top', // 切换器位置
    all: [
      { id: 'v2', dir: 'docs',    label: 'v2.x (最新)' },
      { id: 'v1', dir: 'docs-v1', label: 'v1.x (LTS)' }
    ]
  }
};

3. 特定版本的导航

如果不同版本的导航结构有所不同，您可以在每个版本的源目录中放置一个 navigation.json 文件。docmd 会自动检测并将其用于该特定版本。

// docs-v1/navigation.json
[
  { "title": "旧版安装", "path": "/legacy-setup" },
  { "title": "迁移到 v2", "path": "/migration" }
]

4. 路径保留 (粘性切换)

docmd 会在用户切换版本时自动尝试保留其当前路径。如果用户在 v2 网站的 /api/auth 页面并切换到 v1，引擎将尝试将其路由到 /v1/api/auth。如果目标版本中不存在该页面，则会退回到该版本的首页。

权衡

在单个代码库中存储多个版本会随着时间的推移增加库的大小。对于非常庞大的文档集，请考虑使用 CI/CD 在构建过程中动态拉取旧版本文档目录，而不是将其提交到主分支。