# version
Source: https://blume.ndjp.net/docs/cli/version/
English: https://useblume.dev/docs/cli/version

`blume version` 是你切出[文档版本](/docs/content/versioning/)的方式。给它一个 id，它就会把当前的内容目录树冻结成一份快照，并按文档当时的样子继续对外提供：

```bash
blume version v1.0
```

它会做四件事：

1. **把内容目录树复制**进一个以该 id 命名的目录（`docs/v1.0/`），已有的快照不参与复制。
2. **重写副本内部以根路径开头的链接**，让它们留在快照之内：`/guides/x` 变成 `/v1.0/guides/x`。这涵盖行内链接与图片、引用式定义（`[x]: /guides/x`），以及任意引号写法的 HTML `href` 和 `src` 属性；写明了你的 [`basePath`](/docs/deployment/) 的链接则保留它（`/docs/guides/x` 变成 `/docs/v1.0/guides/x`）。围栏代码和行内代码原样不动，而指向快照里没有副本的页面的链接——生成的 API 参考、像更新日志这样的远程源——仍然指向线上页面。
3. **在 `blume.config.ts` 的 `versions.archived` 中注册这个 id**。首次切出版本会顺带开启版本管理，补上一个 `versions` 块，把该 id 归档，并把线上文档标注为 "Latest"。如果配置的写法它不会去改动，它会给出警告并打印出可供粘贴的条目。
4. **报告它做了什么**：复制了哪些文件、重写了哪些页面的链接，并提醒你归档版本是冻结的，而且 `blume dev` 需要重启才能识别这份快照。

像对待其他内容一样审阅并提交这个新目录。版本如何呈现的每一个细节——切换器、归档页面上的提示、每个版本的标签与徽章——都属于配置，参见[版本管理](/docs/content/versioning/)页。

## 列出版本

不带 id 运行它即可列出已配置的版本：先是当前版本及其标签和徽章，然后是每个归档 id 及其目录。在首次切出版本之前，也就是还没有配置 `versions` 时，它会改为告诉你如何切出一个版本。

```bash
blume version
```

## 选项

- `--force` — 覆盖已经存在的快照目录。不加它时，已存在的目录直接报错，因此一次误触发的重跑不会毁掉某个归档版本。

## 何时拒绝执行

在下列情况下，该命令会以非零码退出且不改动任何东西：

- id 没有以字母开头，或含有字母、数字、点、连字符与下划线之外的字符（要 `v1.0` 而不是 `1.0`，这样一个 id 就永远不会与[数字排序前缀](/docs/content/navigation/)冲突）；
- 项目存在 error 级诊断，因为给一棵坏掉的目录树拍快照等于把这份损坏一起冻结——请先修好它们（`blume doctor` 会列出这些问题）；
- 该 id 已经注册在 `versions.archived` 中；
- 快照目录已存在，而又没有传入 `--force`。