tldr 仓库中 docker save 别名页解析：从保加利亚语页面到 docker image save 实战

docker save 在 Docker CLI 中只是一个快捷别名，真正导出镜像归档的能力全部由 docker image save 提供。本文以 tldr 仓库中的 保加利亚语别名页 为骨架，完整解析 tldr 别名页的文档结构与运行机制，并顺势展开 docker image save 的四种典型导出场景，帮助读者既看懂 tldr 页面的组织方式，也能在终端里把 Docker 镜像导出为 .tar 归档。

关联文档全貌：一篇「一句话」别名页

关联文档 pages.bg/common/docker-save.md 是一篇标准的 tldr 别名页（alias page），全文只有 7 行：

# docker save

> Тази команда е псевдоним на `docker image save`.

- Виж документацията за оригиналната команда:

`tldr docker image save`

逐行拆解其含义：

• # docker save：页面标题，必须与文件名和命令名完全一致（按 style-guide.md 的规则，Markdown 文件名一律小写，标题可以保留原始大小写）；
• > Тази команда е псевдоним на \docker image save`.：引言行，直译为"This command is an alias of docker image save`"，说明该命令只是原命令的一个别名；
• - Виж документацията за оригиналната команда:：示例描述，直译为"View documentation for the original command"（查看原命令的文档）；
• `tldr docker image save`：唯一一条示例命令，提示用户用 tldr docker image save 去查看原命令的完整文档。

这篇页面不展示任何真实导出命令，它的唯一使命是「指路」：当用户输入 tldr docker save 时，tldr 客户端会渲染出这页简介，并告诉用户去查 docker image save。这与英文原版 pages/common/docker-save.md 结构完全一致，只是正文被翻译成了保加利亚语。

别名页机制：为什么 tldr 需要专门为 docker save 建一页

tldr 的别名页机制在 style-guide.md 的 "Aliases" 一节中有明确规定：当一个命令可以用别名调用（例如 vim 可以用 vi 调用）时，就为它创建别名页，把用户导向原命令名。docker save 正是这种场景——Docker CLI 中 docker save 与 docker image save 是等价的，官方文档也只维护 docker image save 这一份权威说明。

别名页的通用模板如下（摘自 translation-templates/alias-pages.md）：

# example

> This command is an alias of `example`.

- View documentation for the original command:

`tldr example`

把占位符 example 替换为实际命令后，就得到 docker-save.md 这样的别名页。模板的价值在于统一约束：所有语言的别名页都遵循「标题 + 别名声明 + 一条 tldr 指路命令」三要素结构，客户端解析起来非常稳定。仓库为包括保加利亚语（bg 小节）在内的数十种语言都维护了预翻译模板，翻译时只需把命令名套进对应语言的模板即可。

顺着别名页走进主命令：docker image save 四种导出姿势

tldr docker image save 会把用户带到原命令页 pages/common/docker-image-save.md，这里才是导出镜像的完整实战内容。原命令页（More information 指向 Docker 官方 CLI 参考）包含 4 个示例，全部可以直接复制运行：

1. 通过 stdout 重定向生成 .tar 归档

docker save {{image}}:{{tag}} > {{path/to/file.tar}}

这是最基础的做法：docker save 默认把归档数据写到标准输出（stdout），用 shell 的 > 重定向即可落盘。适合在管道中配合 gzip 等工具直接生成压缩包。

2. 用 -o / --output 指定输出文件

docker save -o {{path/to/file.tar}} {{image}}:{{tag}}

等价于上一条，但由 Docker 自己负责打开目标文件，不需要 shell 重定向。注意 tldr 页面使用 {{[-o|--output]}} 这种「选项占位符」写法，允许客户端按平台习惯展示短选项 -o 或长选项 --output，两者效果相同。

3. 保存镜像的全部标签

docker save -o {{path/to/file.tar}} {{image_name}}

如果不带 :tag，docker save 会导出该镜像仓库名下的所有标签。适合在需要完整迁移一个镜像的全部版本时使用。

4. 挑选特定标签打包

docker save -o {{path/to/file.tar}} {{image_name:tag1 image_name:tag2 ...}}

一次导出多个指定标签，归档内会同时包含这些不同标签对应的镜像层。这在「只迁移生产环境实际在用的几个标签」的场景下最实用，避免把无关版本一并打包。

从源码看别名页的生成与同步：set-alias-page.py

仓库用 scripts/set-alias-page.py 统一管理别名页的创建与多语言同步，这也解释了为什么 docker-save.md 在近 40 种语言中都有且结构高度一致。脚本的几个关键机制：

• 模板驱动生成：generate_alias_page_content()（scripts/set-alias-page.py#L120-L142）从 alias-pages.md 读取对应语言模板，按顺序把 example 占位符替换成页面标题、原命令名和 tldr 指路命令，最终产出该语言的别名页内容；
• 同步模式：-S/--sync 参数读取英文 pages/ 目录下的全部别名页，再调用 sync_alias_page_to_locale() 逐一同步到各语言目录；-l 可限定单种语言（如 -l bg），-n/--dry-run 可先预览改动而不落盘（见 scripts/set-alias-page.py#L35-L55）；
• 严格模板匹配：get_alias_command_in_page() 会校验页面是否严格符合模板结构（标题行 + 别名声明行 + tldr 命令行的三行骨架），不符合标准的页面会被判定为非别名页，因此翻译页很难偏离模板走样；
• 交互式创建：-p 参数会启动向导，交互收集页面标题、原命令名和文档命令，并实时预览即将生成的页面内容，降低手工拼写错误。

仓库根目录定位则依赖 scripts/_common.py 的 get_tldr_root()：脚本所在路径的父目录中只要存在名为 tldr 的目录，就自动认定其为仓库根，否则回退到 TLDR_ROOT 环境变量。

质量保障：别名页如何通过自动化检查

别名页虽短，同样受到仓库 CI 的严格校验：

• scripts/test-tldr-lint.sh 对每类语言页面运行 tldr-lint：保加利亚语（bg）属于需要额外检查 TLDR003/TLDR004/TLDR015 的语言组，这些规则覆盖标题格式、示例数量、占位符规范等，而英文页面则不做任何忽略（checks=""），要求最严格；
• scripts/test.sh 的 run_tests() 会并行地对 pages* 下所有 .md 运行 markdownlint，再对每个语言目录跑 test-tldr-lint.sh，最后检查 Python 脚本（black、flake8、pytest）与 Shell 脚本（shellcheck）；
• scripts/check-errors.sh 针对页面内容做启发式扫描，例如检查 {{...}} 占位符配对、反引号奇偶性、禁止在描述行中出现占位符等，从侧面约束别名页保持「只有一条 tldr 命令示例」的简洁形态。

如何实际使用这页文档

如果本机已安装任一 tldr 客户端（官方提供 Python 客户端 pipx install tldr、Rust 客户端 brew install tlrc 等，详见 README.md），直接运行：

tldr docker save

即可看到保加利亚语之外、按客户端语言设置选中的 docker-save 别名页；随后按页面提示执行：

tldr docker image save

就能获得 docker image save 的完整示例列表（上述 4 条导出命令）。若需要保加利亚语版本，可指定语言环境让客户端加载 pages.bg 目录下的对应页面；原命令的保加利亚语翻译则位于 pages.ru/common/docker-image-save.md 之外的 pages.bg 语言树中，与英文版保持相同的 4 个示例结构。

小结

从 pages.bg/common/docker-save.md 这 7 行保加利亚语别名页出发，可以看到 tldr 项目把「别名指路」这件事做成了完整的工程闭环：模板统一多语言结构（alias-pages.md），脚本自动化生成与同步（set-alias-page.py），CI 保证格式合规（test-tldr-lint.sh）。而对终端使用者而言，记住一句话即可：docker save 的一切能力都在 docker image save 页面上——用 tldr docker image save 拿到那 4 条可直接落地的导出命令，就能完成单标签、全标签与多标签三种粒度的镜像归档。