tldr 保加利亚语别名页面 bun-x：别名页机制与 bunx 包执行器实战解析-平芜编程栈

文档
教程
知识库

【免费下载链接】tldr

Collaborative cheatsheets for console commands 📚.

项目地址：https://gitcode.com/GitHub_Trending/tl/tldr

本篇文章以 tldr 仓库中的保加利亚语（bg）别名页面 pages.bg/common/bun-x.md 为核心，完整解读 tldr 别名页（alias page）的文档结构与维护机制，并顺藤摸瓜深入bunx原命令页面的全部示例。读完本文，你将掌握 tldr 多语言别名页的编写规范、翻译模板的解析原理、bun x/bunx的实际用法，以及仓库内自动化同步别名页的脚本实现。

一、页面主体：保加利亚语 bun-x 别名页内容逐行解读

该文档是 tldr 项目面向保加利亚语用户提供的命令速查页，全文共 7 行，属于标准的别名页（alias page）格式：

# bun x > Тази команда е псевдоним на `bunx`. - Виж документацията за оригиналната команда: `tldr bunx`

逐行拆解其语义：

# bun x：页面标题，即被记录的命令名称bun x。tldr 约定文件名必须是小写的命令名，因此文件命名为bun-x.md；
> Тази команда е псевдоним наbunx.：保加利亚语描述行，意为"此命令是bunx的别名"，其中bunx以反引号包裹，指向被别名化的原始命令；
- Виж документацията за оригиналната команда:：示例描述，意为"查看原始命令的文档"，以祈使句撰写，符合 tldr 对所有示例描述必须使用祈使句的硬性规范；
`tldr bunx`：实际可执行的命令示例，引导用户通过tldr bunx调出原命令的完整速查页。

该页面与英文源页 pages/common/bun-x.md 结构完全一一对应——英文版写作 "This command is an alias ofbunx." 与 "View documentation for the original command:"。别名页的设计意图很明确：它自身不重复记录任何命令用法，只负责把用户重定向到原始命令的完整文档，从而避免同一命令内容在多处重复维护。

二、别名页机制：tldr 如何用一页重定向解决命令别名问题

许多 CLI 命令存在别名调用方式，例如vi是vim的别名、bun x是bunx的别名。若为每个别名都复制一份完整文档，会导致同一命令内容在仓库内多处重复、翻译与更新成本成倍上升。

tldr 的风格规范 contributing-guides/style-guide.md 明确给出了别名页的标准模板：

# command_name > This command is an alias of `original-command-name`. - View documentation for the original command: `tldr original-command-name`

官方给出的示例正是vi：

# vi > This command is an alias of `vim`. - View documentation for the original command: `tldr vim`

中文版风格规范 contributing-guides/style-guide.zh.md 对别名页机制做了同样的说明：当命令可以通过其他名称调用（如vim通过vi），可以创建别名页面将用户引导至原始命令名称。该规范同时补充了一条重要约定——如果页面已有 8 条示例，则"查看原始命令文档"这一条可以省略（tldr 页面最多允许 8 条示例）。

关键点在于：别名页不写更多信息链接行，也不写任何具体用法示例，唯一示例就是`tldr original_command`。这正是判断"某页是否是别名页"的机器可读特征，后续的脚本维护正是依赖这一特征。

三、多语言翻译模板：保加利亚语模板的存储与结构

为了让 40 多种语言的别名页保持统一结构，tldr 将每种语言的预翻译模板集中存放在一个文件里：contributing-guides/translation-templates/alias-pages.md。

该文件以### bg这样的语言标记分节，每节是一个用example作为占位符的 Markdown 代码块。保加利亚语模板原文如下：

# example > Тази команда е псевдоним на `example`. - Виж документацията за оригиналната команда: `tldr example`

对比实际页面 pages.bg/common/bun-x.md，可以发现页面正是将模板中的三处example占位符分别替换为：

标题处的bun x；
描述行反引号内的bunx（原始命令名）；
命令示例中的tldr bunx（文档查询命令）。

同一文件还包含en、de、fr、zh、zh_TW等语言的对应模板，例如中文模板为"此命令为example的别名。查看原命令的文档：`tldr example`"，繁体中文为"此命令為example的別名。檢視原命令的文件：`tldr example`"。这种"一个文件集中存放全部语言模板"的设计，使任何语言的别名页都可以由脚本自动生成，也为翻译协作提供了唯一的事实来源。

四、原命令实战：bunx 页面完整示例详解

别名页指引用户执行的`tldr bunx`会命中原命令页面 pages/common/bunx.md。该页描述bunx为"执行一个包内的二进制程序（本地已安装或远程拉取）"，并注明bun x可作为bunx的别名使用（Note:bun xcan be used as an alias forbunx）。同时附带指向 Bun 官方文档的"更多信息"链接行。

页面共提供 5 条实战示例，我们逐一展开：

1. 从 registry 下载并执行一个包

bunx {{package_name}} "{{command_argument}}"

bunx的核心场景：包名后直接跟命令参数，bunx会先尝试在本地查找该包的可执行文件，未安装时则自动从 npm 等 registry 临时拉取并执行，无需先npm install。占位符{{package_name}}与{{command_argument}}供 tldr 客户端高亮显示，提示用户替换。

2. 查看本地已安装包的版本

bunx {{package_name}} --version

当目标包已在本地安装时，bunx会优先使用本地版本，--version即打印该版本号，可用于验证包的存在与版本。

3. 强制使用 Bun 运行时执行（而非 Node）

bunx --bun {{package_name}}

这是 Bun 生态最具区分度的选项：--bun强制让目标程序运行在 Bun 运行时之上，而不是默认的 Node.js。对于某些依赖 Node 特定行为的包，这一选项能带来不同的行为或性能表现。

4. 执行与包名不同的二进制

bunx {{[-p|--package]}} {{package_name}} {{command}}

某些包提供的可执行文件名与其包名不一致。{{[-p|--package]}}是 tldr 对"短选项/长选项均可"的书写约定，即-p与--package二选一，用于指定实际的包名，而后面的{{command}}才是真正要执行的二进制命令。

5. 下载并执行指定版本的包

bunx {{package_name@version}} "{{command_argument}}"

通过@语法锁定版本，例如bunx cowsay@2.0.3，实现临时以特定版本执行工具，适合在 CI 或脚本中做版本固定。

五、仓库实现：set-alias-page.py 如何自动化生成与同步别名页

别名页的创建与多语言同步在 tldr 仓库中由脚本 scripts/set-alias-page.py 完成，其工作流程与上文提到的模板文件直接对应，可以从源码层面验证别名页机制的实现原理。

模板解析：脚本调用get_templates(root, "alias-pages.md")（实现在 scripts/_common.py）读取模板文件，按### 语言标记分节，提取每个```markdown代码块中的模板文本，最终得到语言 → 模板的字典。

占位符替换：核心函数generate_alias_page_content()将模板中的example占位符依序替换为页面标题、原始命令名、文档查询命令：

result = template_content.replace(template_command, page_content.title, 1) result = result.replace(template_command, page_content.original_command, 1) result = result.replace(template_command, page_content.documentation_command)

其中template_command = "example"，三次replace恰好对应模板中标题、描述行、命令示例三处占位符——这就是为什么模板必须用example作为占位符的原因。

识别既有别名页：get_alias_command_in_page()通过正则匹配页面的别名描述行（`> ...example``" 形态）与 ``tldr ...` `` 命令行，从已有页面中反解出标题、原始命令与文档命令，用于判断页面是否已存在、是否需要更新。

批量同步：main()中的--sync选项会扫描英文目录pages下的全部别名页，然后调用sync_alias_page_to_locale()将每个别名页同步到pages.bg、pages.de、pages.zh等所有语言目录（由get_pages_dirs()收集所有以pages开头的目录）。典型用法：

python3 scripts/set-alias-page.py --sync # 同步全部语言 python3 scripts/set-alias-page.py --sync --language bg # 仅同步保加利亚语 python3 scripts/set-alias-page.py --sync --dry-run # 预览变更而不落盘 python3 scripts/set-alias-page.py --sync --stage # 同步并 git stage

另有交互式-p选项引导创建单个新别名页。脚本文档字符串特别提醒：同步模式会产生较多误报，建议只使用-l LANGUAGE限定语言并人工复核 stage 的变更。

六、本地查看与校验：把别名页落到实际使用

在本地实践这条"别名 → 原命令"链路非常直接。安装任一 tldr 客户端后：

tldr bun-x # 查看别名页：得知它是 bunx 的别名 tldr bunx # 查看原命令页：获得 5 条完整用法示例

提交格式校验方面，tldr 提供tldr-lint工具，可参照 contributing-guides/style-guide.zh.md 的说明进行本地检查：

npm install --global tldr-lint tldr-lint pages.bg/common/bun-x.md

若使用 Node.js 官方客户端，还可以用--render参数本地预览页面渲染效果。整个别名页生态的闭环在于：每种语言的模板集中存放 → 脚本按模板生成/同步页面 → 客户端渲染时高亮占位符 → 用户经别名页一键跳转原命令文档，既保证了 40+ 语言内容一致性，也把单条命令的文档维护成本降到了最低。