30分钟搭建命令行速查系统：从安装到自定义cheatsheet

每次敲命令都要翻 Google？用 navi 建一个属于自己的命令行速查库

作为后端开发，你一定有过这些时刻：

• 突然要给容器改名，却死活想不起 Docker 重定向的 flag 是 -v 还是 --bind；
• 写部署脚本时翻三个月前的笔记找当年那行 awk | sed 组合拳；
• 新同事问你某个 git 命令怎么用，你当场打开 Stack Overflow 边查边尴尬……

这些问题我全经历过。直到我发现了 navi——一个 1.7 万+ 星的命令行交互式速查表工具。

今天这篇文章，我会手把手带你完成一件事：在 30 分钟内，从零搭建一套属于自己的命令行速查系统。 学完后，你再也不用靠记忆力背命令，也不用在浏览器里搜索那些敲过无数次的组合。所有常用命令、参数、示例，全部本地化、可搜索、可一键执行。

跟着做就行，我们开始。

前置条件

本文不需要你懂 Rust 或了解 navi 的源码。你只需要：

• 一台运行 macOS / Linux 的机器（Windows 用户可通过 WSL2 或 Git Bash 操作）；
• 已安装 Homebrew（macOS）或对应包管理器；或者你有 Cargo（Rust 的包管理器）；
• 日常使用 bash / zsh / fish 中的任意一种 Shell；
• 对基本的命令行操作有概念即可（cd、ls 这类）。

小提示：navi 底层使用了 fzf（模糊搜索工具），如果你还没装，安装 navi 时通常会自动处理依赖。macOS 用户如果没有 Homebrew，先跑一行 brew 官网的安装脚本即可。

第一步：安装 navi

官方推荐用 Homebrew 一行搞定：

brew install navi

这背后发生了什么？Homebrew 会从社区仓库拉取预编译好的 navi 二进制文件，放到你的系统 PATH 里，顺便会确保 fzf 等依赖就位。这是最省心的方式，适合大多数开发者。

如果你不用 Homebrew 怎么办？ 还有几种常见选择：

• 你有 Cargo：cargo install navi
• 你喜欢用 SDKMAN 或 Nix 等工具：navi 也在 repology 上有收录，具体可看项目文档。
• 想从源码编译：Clone 仓库后 make install 即可，但一般没必要。

安装完成后，验证一下：

navi --version

能看到版本号就说明安装成功了。

第二步：首次启动 & 加载社区速查表

直接在终端输入 navi 回车。

第一次启动时，navi 会提示你下载社区维护的速查表。这些速查表涵盖了 git、docker、kubectl、ffmpeg、tmux、curl 等几十个常用工具，相当于一个"开箱即用"的命令字典。

为什么先跑社区库？ 因为这是你理解 navi 运作方式最快的途径。社区库的文件格式就是 navi 的标准格式，看完你自然就知道怎么写自己的了。

下载完成后，你会进入一个交互式界面：上方是分类标签（tags），下方是具体命令。用方向键或 / 进行模糊搜索，比如输入 docker，就会过滤出所有和 Docker 相关的命令条目。选中一条按回车，命令就会直接出现在你的终端输入行上，稍作修改就能执行。

第三步：编写你自己的 cheatsheet

社区库虽好，但终究是通用的。真正让 navi 发挥价值的，是你自己写的、贴合你日常工作的速查表。

navi 的速查表文件放在 ~/.local/share/navi/cheats/ 目录下（首次运行后自动生成）。文件扩展名是 .cheat，内容长这样：

% docker, deployment

## 查看所有运行中的容器
docker ps

## 查看容器日志（后 100 行）
docker logs --tail 100 -f <container_name_or_id>

$ container_name_or_id: docker ps --format "{{.ID}} {{.Names}}"

逐行解释：

• % docker, deployment 是 tags（标签），用于分类和快捷过滤。% 开头，后面跟逗号分隔的标签名。
• # 查看... 是命令的描述行，以 # 开头，展示时会作为提示。
• 下一行是实际要执行的命令。
• $ container_name_or_id: ... 是参数自动补全。当你在 navi 里选中这条命令时，它会对 <container_name_or_id> 这个变量运行后面的 shell 命令（这里列出当前运行的容器 ID 和名称），然后弹出一个选择列表让你挑。这就是 navi 最酷的地方：你不用记住容器 ID，它能自动帮你列出来。

你可以直接创建一个新的 .cheat 文件放在 cheats/ 目录下，下次启动 navi 就会自动加载。推荐做法：每个工具或场景一个文件，比如 my-git.cheat、my-deploy.cheat，方便管理。

实战演示：写一份你的「日常部署」速查表

假设你日常需要操作 K8s 和 Docker，每次都要反复记各种命令。我们来做一个完整示例：

1. 在 ~/.local/share/navi/cheats/ 下新建文件 my-workflow.cheat
2. 写入以下内容：

% k8s, deploy

## 查看 Pod 状态
kubectl get pods -n <namespace> | grep <app_name>

$ namespace: kubectl get namespaces --no-headers | awk '{print $1}'
$ app_name: kubectl get pods --all-namespaces --no-headers | awk '{print $4}' | sort -u

## 重启某个 Deployment
kubectl rollout restart deployment/<deployment_name> -n <namespace>

$ deployment_name: kubectl get deployments -n <namespace> --no-headers | awk '{print $1}'
$ namespace: kubectl get namespaces --no-headers | awk '{print $1}'

## 查看最近 50 条应用日志
kubectl logs -n <namespace> deploy/<deployment_name> --tail=50

$ namespace: kubectl get namespaces --no-headers | awk '{print $1}'
$ deployment_name: kubectl get deployments -n <namespace> --no-headers | awk '{print $1}'

保存后，回到终端输入 navi，搜索 k8s 标签，你就会看到自己刚写的三条命令全部出现了！选中任意一条，变量参数会自动弹出选择框，选完直接执行，整个过程不用离开终端。

进阶：把 navi 集成到你的 Shell

上面我们是通过手动输入 navi 来使用的。但其实可以更丝滑：把 navi 设置成 Shell 快捷键（widget）。

以 zsh 为例，官方文档提供了安装 Shell widget 的指引。装好后，你只需要按一个快捷键（比如 ALT+C 或 CTRL+G），navi 的搜索界面就会直接弹出在当前终端行上，选中命令后它会填充到你的命令行上，你可以修改、回车执行。好处是：命令会完整记录在你的 Shell 历史里，而不是只记一个 navi。

如果你用 Tmux 或在远程服务器工作，navi 还支持 Tmux widget，用法类似，让你在任意 SSH 会话中都能快速调出速查表。

具体配置方法可以在项目文档 docs/widgets/ 目录下找到。

常见问题 & 踩坑提醒

Q: 第一次运行 navi 没弹出下载提示怎么办？
手动运行 navi repo browse 浏览和导入社区速查表。如果网络不通（比如在公司内网），你也可以手动 clone 速查表仓库到 ~/.local/share/navi/cheats/repos/ 下。

Q: 自定义 .cheat 写完后 navi 没识别到？
检查文件编码是否为 UTF-8，确保 tags 行以 % 开头（百分号后有个空格）。可以用 navi --dry-run 预览解析结果排查语法错误。

Q: 参数补全命令跑得太慢？ $ 后面的命令每次都会执行，如果返回数据量大会有延迟。建议在补全命令里加过滤条件（像上面那样用 awk 精确提取字段），或者缓存结果。

Q: 能和其他工具（如 tldr）一起用吗？
可以。navi 支持导入 tldr 和 cheat.sh 的速查表格式。具体操作见文档 docs/cheatsheet/ 部分。

总结一下

今天我们做了这几件事：

1. 用 brew install navi 完成安装
2. 首次运行拉取社区速查表，熟悉交互式浏览和搜索
3. 手写了一份 .cheat 文件，理解 tags、命令、参数自动补全的语法
4. 实操了一份 K8s/Docker 部署速查表，体验完整工作流
5. 了解了 Shell widget 集成思路，让使用更顺滑
6. 整理了几个踩坑点，帮你少走弯路

现在你已经有了一套完全属于自己的命令行速查系统。建议趁热打铁：把你这周用过的命令整理成 .cheat 文件，下次用的时候直接搜，你会发现效率提升是立竿见影的。

下一步，你可以去看看 navi 的 --help，了解子命令（如 navi fn、navi best）的更多玩法；也可以尝试把 navi 用在 CI/CD 脚本里，或者结合 TiddlyWiki 做笔记联动。

工具的本质是替你记住那些你不想记的东西。有了 navi，把脑力留给真正需要思考的事吧。