如果你和我一样，每年都要在至少三台机器上重建开发环境，那你大概率经历过这种场面：打开一台新电脑，先装 Homebrew，再装 apt，花一个下午把.zshrc里的 alias 一个个扒回来，然后发现 tmux 配色不对、Neovim 插件全红、Git 用户信息忘了配。这种事情我重复了五年，直到有一天决定不再重来。于是有了 openrig，一个专门管理“工作台配置”的开源方案。
rig 在极客圈里一般指“装备”或“工作台”，有人把整台游戏电脑叫 gaming rig，有人把录音设备叫 recording rig。openrig 的意思很直白：把我这套开发工作台的配置完全打开，让任何一台新机器都能一键重建。它不只是把点文件（dotfiles）同步一下，而是一个带安装脚本、模块开关、模板变量和自检机制的完整配置体系。后面我会把目录结构、核心脚本、实测踩坑全部拆开讲，适合正在维护自己 dotfiles 的开发者，也适合刚入门想建立一套规范化终端环境的新手。
1. 为什么我会开源一套叫 openrig 的开发环境
1.1 痛点的起点：配置散落，没有一个人说得清
我的处境可能跟很多人类似：办公用 macOS，家里用 Linux，还有一台常年在跑的云服务器。三台机器的系统不同、包管理器不同、预装工具也不同。过去我的做法是“哪台缺什么就装什么”，结果就是每台机器的配置都不一样，.zshrc越改越长，alias 经常在这台有、那台没有。
真正让我崩溃的是一次系统重装。我当时自信地把 Home 目录备份了，但恢复后发现.config里各个程序的自定义设置根本没有被统一管理，Neovim 的插件依赖、tmux 的会话恢复脚本、Git 的全局 ignore，全都要手动找回来。折腾了两天，最后依然有几个旧工具链的小癖好没复原。那时候我就意识到：一个开发环境如果不以代码形式管理，本质上就是不可复现的黑历史。
1.2 openrig 的定位：比 dotfiles 多走一步
dotfiles 这个词大家应该不陌生，把.zshrc、.tmux.conf、.gitconfig放到一个 Git 仓库里，到新机器 clone 下来再软链接过去。它能解决“配置文件丢失”的问题，但它不管“依赖装没装”“版本对不对”“符号链接建没建成功”。
openrig 在我的定义里是“dotfiles 的超集”。它除了放配置文件，还包含：
- 引导脚本
bootstrap.sh，在新机器上自动识别系统并安装基础依赖； - 模块化目录结构，每个工具一个模块，可单独开关；
- 统一的安装与刷新命令，不用再记零散的
ln -s操作； - 模板变量系统，把机器相关的差异（用户名、工作目录、Git 身份）单独抽出来；
- 自检脚本，安装后告诉你哪些配置还没生效。
一句话，dotfiles 是“把配置存下来”，openrig 是“把整套环境长出来”。
1.3 为什么不直接用整机镜像或容器
我曾认真考虑过用 Docker 或整机镜像来解决问题，但实际试下来不划算。下面是我对比过的几条路线，各有各的适用场景，不过对我来说 openrig 是最合适的。
| 方案 | 恢复速度 | 维护成本 | 适用场景 |
|---|---|---|---|
| 整机镜像 / 磁盘克隆 | 最快 | 高，镜像体量大，跨硬件容易出问题 | 同型号机器批量部署 |
| 远程容器 / 云 IDE | 快 | 中，但本地终端、输入法、GUI 工具链体验差 | 项目隔离、多人协作 |
| 纯 dotfiles 仓库 | 慢 | 低，但只管配置文件不管依赖 | 单机备份 |
| openrig 这类配置系统 | 较快 | 中，脚本本身需要维护 | 多平台个人开发环境、团队新机初始化 |
容器适合跑服务，但不太适合当日常开发环境。编辑器要装插件，终端要连系统剪贴板，输入法要跟桌面环境配合，这些在容器里都要额外打洞。整机镜像则太重，换一块硬盘都可能触发一堆驱动问题。配置系统的最大优势是轻和透明：每一行配置都能 review，每次变更都进 Git 历史，出了问题可以随时回滚。
1.4 什么人适合用这套思路
如果你满足下面任意一条，我建议你也照着 openrig 的思路整理一套自己的配置系统：
- 有两台以上设备，且系统不完全相同；
- 每半年至少重装一次系统、换一次电脑或者入职新公司需要配新机；
- 受够了某个工具在某台机器上“就是跟别的不一样”；
- 想给团队做一套统一的新人开发环境模板。
我不保证 openrig 本身能让所有环境秒级一致，但至少能让你告别“人肉 beancount 配置”的日子。下面进入正题，看看这套方案到底怎么搭。
2. 目录结构：每个模块就是一个可以独立开关的积木
2.1 模块化约定：install.sh + config 目录
openrig 的核心是模块。每个模块负责一个工具或一组工具，彼此之间尽量不耦合。我定的约定很简单：一个模块就是一个子目录，目录名就是模块名，模块下必须有install.sh，负责安装和生成配置；如果这个工具需要配置文件，就放在config/目录里，安装完成后由管理脚本软链到用户目录。
这样做的好处是，当你只想在新机器上装 Neovim 相关配置，不想要我喜欢的 tmux 布局时，可以直接用--only neovim参数跳过其他模块。模块是离散的，开关由外层脚本控制，而不是在安装脚本里写一堆 if 判断整个工具链。
2.2 顶层结构一览
我的仓库结构如下，你可以直接作为参考模板：
openrig/ ├── bootstrap.sh ├── manager.sh ├── vars/ │ ├── env.sh │ └── secrets.age ├── modules/ │ ├── zsh/ │ │ ├── install.sh │ │ └── config/ │ │ ├── .zshrc │ │ └── aliases.zsh │ ├── tmux/ │ │ ├── install.sh │ │ └── config/.tmux.conf │ ├── neovim/ │ │ ├── install.sh │ │ └── config/ │ ├── git/ │ │ ├── install.sh │ │ └── config/ │ ├── tools/ │ │ ├── install.sh │ │ └── config/ │ └── ... ├── templates/ │ └── gitconfig.tmpl └── README.mdbootstrap.sh是入口，在全新机器上最先执行；manager.sh是日常维护工具，负责创建软链接、调用模块安装脚本、刷新配置；vars/env.sh放机器相关的变量，比如USER_NAME、WORK_DIR；templates/存放需要动态生成的配置文件模板。
2.3 符号链接的生成规则
配置文件的生效方式，我采用“先备份，后软链”的策略，而不是直接复制。原因很简单：如果你在新机器上改了.zshrc，你希望改动回到 Git 仓库里以便管理，那就必须让编辑器打开的是同一个文件。软链接是符合直觉的方案。
manager.sh的核心逻辑大致是这样：
- 遍历模块下所有
config/*文件； - 对每个文件，检查用户目录下是否已有同名文件；
- 如果已有且不是指向当前仓库的链接，就先重命名为
.bak再创建链接； - 如果已经是指向当前仓库的链接，就跳过；
- 执行每个模块的
install.sh，传入--verbose或--dry-run选项。
这么一套流程保证了脚本可以重复执行而不产生副作用，也就是常说的幂等。我第一次跑完之后又跑了一遍，没有任何报错，也不会把已有的配置备份文件再次覆盖。
2.4 模板变量：把“机器差异”和“个人偏好”分开
同一个配置，在不同机器上往往只有几个变量不同：Git 的 user.name、某些工具的下载目录、代理端口等。如果全部写死在配置里，仓库就无法在不同电脑间通用。
我的做法是利用一个简单的模板替换：templates/gitconfig.tmpl里写{{USER_NAME}}这样的占位符，install.sh在生成配置时读取vars/env.sh里的变量并替换。我并不为了这个功能引入 Ruby 的 ERB 或 Python 的 Jinja2，因为这些工具本身可能还没装好，用 Shell 的sed做简单替换就够了。等到有一天模板复杂到 sed 搞不定，再迁移到更重的工具也不迟。
模板这套机制帮我解决了最头疼的 Git 身份问题。办公机器上我想让提交记录显示公司邮箱，家里的机器想显示个人邮箱，这个差异现在只在vars/env.sh里体现，配置文件模板完全不用改。
2.5 模块盘点：我实际维护了哪些模块
| 模块名 | 作用 | 亮点 |
|---|---|---|
| zsh | Shell 配置、别名、历史、补全 | 手动维护插件清单，启动速度稳定 |
| tmux | 终端复用、会话持久化 | 自定义前缀键、复制模式接入系统剪贴板 |
| neovim | 编辑器配置、插件管理 | 使用 lazy.nvim，插件版本锁定在 lock 文件里 |
| git | 全局配置、模板、常用 alias | 区分工作/个人 Git 身份 |
| tools | 常用命令行工具集合 | 用函数统一管理不同系统的安装命令 |
| ssh | SSH 客户端配置、known_hosts 管理 | 密钥明文不入库，只放配置引用 |
每个模块都要保证能独立安装、独立卸载。模块之间如果需要依赖，我会在install.sh开头显式声明，比如 neovim 模块依赖 tools 模块里的git和curl，脚本启动时会先检查它们是否存在。这套依赖关系写得越清楚，排错就越简单。
3. 核心实现：从零搭起一套可复用的工作台配置
3.1 bootstrap.sh：一条命令完成新机器初始化
新机器最痛苦的部分是从零开始。openrig 的bootstrap.sh解决的就是“拿到一台新机，clone 仓库后跑什么”。
脚本的主力逻辑可以简化成下面这段：
#!/usr/bin/env bash set -euo pipefail DRY_RUN="${DRY_RUN:-0}" VERBOSE="${VERBOSE:-0}" # 检测操作系统与包管理器 detect_os() { case "$(uname -s)" in Darwin) OS="macos"; PKG_MGR="brew" ;; Linux) OS="linux"; detect_linux_pkgmgr ;; *) echo "unsupported OS"; exit 1 ;; esac } # 执行命令前的 dry-run 钩子 run() { if [ "$DRY_RUN" -eq 1 ]; then echo "DRY-RUN: $*" else "$@" fi } # 安装一个包，支持多个包管理器 install_pkg() { local pkg="$1" case "$PKG_MGR" in brew) run brew install "$pkg" ;; apt) run sudo apt-get install -y "$pkg" ;; pacman) run sudo pacman -S --noconfirm "$pkg" ;; esac } detect_os echo "Detected: $OS / $PKG_MGR" install_pkg git install_pkg curl # 继续调用 manager.sh 处理模块 bash "$(dirname "$0")/manager.sh" "$@"这里set -euo pipefail是三件套保险：-e让脚本在出错时立刻退出，避免带着错误继续跑；-u让未定义的变量直接报错，防止$PKG_MGR拼错导致静默失败；-o pipefail让管道中任何一环出错都能被捕获。
dry-run 是我强烈建议每个人保留的功能。你可以在DRY_RUN=1的情况下看到这台新机器将被安装的每一个包、执行的每一条命令，而不是在 root 权限下直接开始装一堆软件。如果哪一步不对劲，改完再正式跑，能避免一边安装一边发现脚本逻辑错了然后手动清理的尴尬。
3.2 跨平台包安装的抽象函数
openrig 要用的核心工具其实不多：Git、curl、zsh、tmux、ripgrep、fzf、fd、lazygit 这些。但它们在 macOS 上要用brew install，在 Debian 系上要用apt-get install，在 Arch 系上要用pacman -S。如果每个模块都写一遍包管理器分支，仓库里会到处是 if。
所以我把包安装收敛成一个公共函数install_pkg，放在bootstrap.sh里。所有模块只写“我要装什么”，不关心底层的包管理细节。new 模块加入时，也不用去关心“用户是 Ubuntu 还是 Fedora”。
Fedora 我额外加了一个分支，因为dnf的用法和其他几个不太一样。包管理器抽象这层做得越薄越好，别把“解析依赖”“安装编译选项”这种逻辑也塞进去，否则这个函数会变成技术债的重灾区。
3.3 zsh + tmux + neovim 三件套的配合
这三个工具是我日常开发的主力，它们不是孤立的，配置也需要互相配合。
zsh 模块里我没有用 Oh My Zsh，原因不是它不好，而是它启动有点重。我直接手动维护.zshrc，引入必要的插件补全和提示，并把 alias 单独拆到aliases.zsh里。zsh 的加载顺序我按照“环境变量 - 插件 - alias - 函数”排列，避免出现 alias 定义时的依赖问题。
tmux 模块里我改了前缀键，从默认的C-b改成C-a，这样更顺手。我加上了鼠标支持和所见即所得的复制模式，让它能直接读取系统剪贴板。最关键的是开启了会话持久化，配合tmux-resurrect和tmux-continuum，重启机器后能恢复到之前的窗口布局。
neovim 模块用的是 lazy.nvim 做插件管理。它有个 lock 文件，会把每个插件的 commit 锁住，避免某一天某个插件更新后整个编辑器崩掉。我的init.lua里有一个非常小的核心片段：
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" if not vim.loop.fs_stat(lazypath) then vim.fn.system({ "git", "clone", "https://github.com/folke/lazy.nvim.git", lazypath, }) end vim.opt.rtp:prepend(lazypath) require("lazy").setup("plugins")第一次打开 nvim 时它会自动拉取 lazy.nvim，然后根据plugins/目录下的配置加载所有插件。新机器装完 openrig 后，我第一次打开 neovim 只需要等几秒下载插件，之后就是熟悉的编辑界面。这套组合把“新环境适应成本”降到了非常低。
3.4 Git 与 SSH 的配置模板
Git 配置里最让我受益的是一个叫 conditional include 的机制。它允许我按目录自动切换不同的 Git 身份：所有放在~/work/下的仓库自动使用公司邮箱，所有个人目录下的仓库使用个人邮箱。配置文件模板大致长这样：
[user] name = {{USER_NAME}} email = {{USER_EMAIL}} [includeIf "gitdir:~/work/"] path = ~/.gitconfig.work这个方案不需要每次手动改 remote URL，也不用在本地仓库里写 user.email。配合 openrig 的模板变量，{{USER_NAME}}和{{USER_EMAIL}}会在安装时被替换成当前机器的实际值，非常干净。
SSH 模块我比较保守：私钥永远不进仓库。仓库里只放~/.ssh/config的模板，包含 Host 别名、登录用户、端口等。私钥和敏感凭证单独使用系统钥匙串或 age 加密文件管理。团队场景下，我甚至不建议把公钥放进仓库，因为公钥也是敏感信息的一部分，轮换起来同样麻烦。
4. 上线之后踩过的真实坑
openrig 看着简单，真正跑起来之后遇到的坑一点也不少。下面这几个都是我实际调试过的，每一个都曾经让我怀疑脚本是不是又被环境“偷偷改了设定”。
4.1 同样一条命令，macOS 和 Linux 行为完全不一样
最开始我的manager.sh里用sed -i改模板文件，在 Linux 上跑得挺好，到 macOS 上直接报sed: -i may not be used with stdin。原因很经典：macOS 自带的 BSD sed 和 GNU sed 的-i参数写法不同。
排查过程花了我半个小时，最后解决方案是在脚本里加一个检测函数，如果检测到是 macOS，就用gsed替代。类似的问题还出现在find命令的参数、readlink -f、date格式化这些地方。所以后来我给 openrig 定了一条铁律：涉及到跨平台差异的命令，一律用小函数包一层，不允许直接裸写在模块里。
4.2 包管理器不能硬编码
我第一版脚本里写死了apt-get，因为我在 Ubuntu 上开发。后来放到一台 Arch 机器上跑，直接失败。那次的错误信息很蠢，它告诉我apt-get: command not found，但脚本依然尝试继续执行，直到后面一个依赖缺失才整体崩掉。
从那以后我把包管理器抽象成了函数，并且坚持在bootstrap.sh最前面检测系统。另外，我意识到sudo的使用也要小心。在 macOS 上brew一般不需要 sudo，在 Arch 上pacman必须用 sudo，两个系统上的权限模型不同。不在抽象层处理这个问题，用户就会被莫名其妙的权限错误卡住。
4.3 “~” 在配置文件里不一定等于 HOME
这是个很隐蔽的坑。在 zsh 里，~会被展开成$HOME，但在某些 tmux 启动的执行环境中，~的展开依赖 SHELL 变量，如果 SHELL 没有正确设置，~/.config就真的成了一个叫“~”的目录。
我在做软链时用了ln -s，源路径写的是~/.zshrc，结果发现有一部分机器上符号链接目标变成了/home/user/~/.zshrc，直接失效。排查之后，我把所有脚本内部的路径统一改写为"${HOME}/.zshrc"。这是给后来人的第一个建议：脚本里永远别用~，只用$HOME。
4.4 环境变量串台，tmux 和 zsh 互相同步
tmux 启动时会向所有会话推送环境变量。我的 zsh 模块里配置了一些工具链的 PATH，如果同时在 tmux 里开了好几个窗格，一个窗格里更新的PATH可能会被其他窗格继承，导致某个工具时灵时不灵。
我的解决办法是：不在全局.zshrc里塞项目相关的环境变量，而是让每个项目目录维护自己的.envrc，配合 direnv 在进入目录时按需加载。全局 zsh 只保留工具链本身的东西，比如 autoload 和通用 alias。这样环境变量不会互相污染，出问题的范围也被限制在单个项目里。
4.5 差点把密钥提交进仓库
有一次为了测试 SSH 模块，我把一段真实私钥内容临时放进了某个模块的配置文件里，同时还在新建分支和提交。如果不是我设置了pre-commit钩子去扫描BEGIN OPENSSH PRIVATE KEY字样，那次提交就会带着私钥推到远端。
从那以后 openrig 里加了两个安全机制：一个是.gitignore里强制忽略密钥文件和.env类文件；另一个是 Git 钩子，在提交前扫描常见机密关键字。如果你维护类似的仓库，我强烈建议至少做到这两条。密钥一旦推上去，即使马上删除提交，第三方也可能已经克隆到了。
4.6 工具升级太快，配置反而先把自己升级坏了
Neovim 的不同版本对插件 API 的支持差异很大。有一段时间我升级到 nightly 版本，结果一个自动补全插件直接报错，我又没有锁定版本，回滚非常痛苦。
后来我在 neovim 模块里增加了版本锁定机制：指定一个经过测试的稳定版本，而不是默认安装 nightly。zsh 和 tmux 也类似，我会在vars/env.sh里记录工具的最低版本要求，安装时做一次版本比对。这套机制不能说百分百免疫升级问题，但至少把意外换挡的概率降下来不少。
5. 把 openrig 从个人项目扩展成团队级工作台
5.1 团队标准与个人偏好的隔离
如果你想把 openrig 的这套思路应用到团队，最容易踩的雷就是“统一一切”。任何团队里都会有这样的场景：标准化的 Git 别名大家愿意接受，但 vim 和 emacs 的争论根本不该由配置文件来解决。
我在团队版里做了一层覆盖机制：基础模块提供团队公共配置，比如代码风格提交前缀、通用 commit 模板、CI 工具链；个人覆盖模块放在另一个目录，由每个人自己维护。团队模块更新的历史记录要尽量清晰，让人一看就知道“为什么这么改”。
5.2 新人机器的无人值守部署
团队场景里，让一个新人在第一天就跑起来，价值非常高。我的做法是把 openrig 的部署命令继续简化成一条远程命令：先让系统里安装 Git，再 clone 仓库，最后执行bootstrap.sh。
这里必须留个心眼：无论脚本多完善，都要让新人先跑DRY_RUN=1模式看一遍将要执行的命令，确认没有不可理解的操作再正式安装。我不建议做成完全的无人值守，因为一些交互式配置仍然需要人工确认。智能一点的方向是让脚本自己检测当前系统状态，输出一份“待办清单”，减少新人的学习成本。
5.3 我每三个月做一次“从零重建演练”
这个习惯来自一次惨痛经历：我的 macOS 升级失败，不得不恢复数据，结果发现保存的配置文件里有一条只有我自己才看得懂的怪异注释，却不知道它原本是在解决什么问题。
从那以后，我每三个月会在虚拟机或一台闲置机器上跑一次完整的从零重建流程。模拟场景包括：新系统、无任何工具链、只有一个空目录和 Git 权限。这样才能确保bootstrap.sh不是在特定环境下的偶然成功，而是真正可复现。每次演练几乎都能发现一个被遗漏的依赖，这个投入非常值。
5.4 未来的扩展方向
openrig 现在已经不局限于终端配置文件了，我在往“开发环境巡检”的方向扩展。比如在安装完成后生成一份巡检报告，列出尚未生效的配置、需要手动导入的密钥、版本过低的工具。这个巡检功能本质上就是把安装期间的状态检查从调试期保持到日常使用期。
另外一个方向是集成语言工具链的版本管理。以前每个模块里可能都要写“安装 Python 3.12”“安装 Node 20”，现在我更倾向于在 openrig 元层面统一管理运行时版本，避免不同项目之间因为工具链版本打架。这是一个还在演化中的功能，等稳定了我再单独写一篇文章聊聊细节。
如果你也想动手整理自己的 openrig，我的建议是步子别迈太大。先把最常用的三到五个工具的配置收进来，跑通从零部署的流程，再逐步加入更多模块。这套东西真正值钱的地方不在脚本本身，而在你每一次踩坑后写下的注释、每一次环境变化后及时更新的维护习惯。把开发环境当作代码来管理，它就会像代码一样，给你一个可回滚、可审计、可交付的确定性。
