一切开始于一个很糟心的周四下午。我同时维护着三个项目：一个是公司的微服务仓库，一个是我自己的开源命令行工具，还有一个是帮朋友写的数据处理脚本。每次切换项目，我都要手动改环境变量、切换Node版本、调整Shell别名、甚至要记住不同的代码风格规范。最崩溃的是有一次我在开源项目里提交代码，居然把公司的私有源地址带了进去，虽然及时发现没有外泄，但那种后背发凉的感觉真的不想再体验第二次。
后来我注意到了一个概念：context-mode。简单说，就是把“上下文”当成一种可切换的模式。What this means is：每个项目或任务，都应该有一整套自己的环境配置、目录映射、Shell别名、编辑器设置，切换项目时，这些配置应该像电灯开关一样一键切换，而不是每次手动去逐个调整。我花了一个周末写了一个叫context-mode的小工具，这个工具没有用任何复杂的框架，也没有网络服务，就是一个纯 Shell 脚本加一个约定好的目录结构。但它解决了我过去半年最头疼的问题。
如果你也有类似的切换烦恼，或者你在用类似 ai 编程助手时总觉得“上下文”不够干净，这篇博客可能对你有用。我会从最初的需求拆解、核心设计、实现细节，到实测和踩坑记录，完整讲一遍。每一步都包含我当时的真实选择和理由，不是网上那种只贴代码不解释的教程。
1. 为什么我会自己写一个context-mode工具
1.1 被上下文切换折磨的真实场景
先说说我每天的工作流有多混乱。我有三套环境需要维护：
- 项目A（公司微服务）：Java 11、Maven 私服地址指向公司内网、数据库连接串需要注入到当前 Shell、Git 提交信息需要带公司工号前缀。
- 项目B（开源CLI工具）：Node 16、npm 源指向官方 registry、Shell 里要加载一些自定义的调试函数、Git 提交信息需要符合 Conventional Commits。
- 项目C（数据处理脚本）：Python 3.9、需要激活虚拟环境 venv、每天会重新生成数据目录、我习惯在这里把
ls别名为ls -lh --color=auto。
以前我用最原始的方式：打开终端后先判断自己在哪个目录，然后手动export JAVA_HOME=...、source ~/venv/bin/activate、再设置alias lg="git log --oneline"。每天反复操作，至少浪费十五分钟。而且这种“凭借肌肉记忆操作”的方式最容易出错，比如：
- 忘记卸载旧环境的变量，比如在项目B里还残留着
JAVA_HOME。 - 使用了错误的 npm registry，拉包时要么慢要么失败。
- 因为没加载项目B的调试函数，执行
debug-server时报command not found。
更隐蔽的问题是“上下文污染”。例如我把公司环境的MAVEN_OPTS带到了自己的开源项目里，导致编译行为异常，排查了很久才发现是环境变量的问题。我在想：如果有一个工具能定义好“每个项目的上下文”，切换时统一加载，退出时统一清理，是不是就能避免这些乱七八糟的错误？
这就是context-mode最初的灵感：不是做一个通用的“项目管理器”，而是做一个轻量的“上下文切换器”。它只服务于一个目标：让每个阶段/项目，拥有一套可以被一键激活和撤销的完整配置束。
1.2 现有方案的痛点：配置太重、切换太慢
在动手前，我评估了几种现成的工具。第一类是 direnv，它能在你进入目录时自动加载.envrc，退出目录时不一定会完全恢复现场（需要额外配置）。direnv 的优点是自动，但自动也是一把双刃剑：当你从一个目录快速cd到另一个目录时，Shell 的当前目录不断变化，direnv 的加载逻辑有时会滞后，而且它的 hook 需要依赖 shell 的PROMPT_COMMAND，在 zsh 和 bash 之间的行为有细微差异。更重要的是，direnv 是“按目录绑定上下文”，但我不总是按目录切换。比如我在做某个任务时，即使当前工作目录不变，我也需要临时切换到另一个上下文，比如从“开发模式”切换到“预发布模式”。
第二类是 virtualenvwrapper / conda 这类环境管理工具。它们只解决 Python 环境的问题，管不了 Java、Node、Git 配置、Shell 别名这些。第三个选择是自己写 shell 函数来source不同的配置脚本，但那样还是手动操作，而且变量残留问题依然存在。
我真正想要的是这样的体验：
- 在终端输入
context-mode use service-api，就完成服务端项目的全量环境加载。 - 输入
context-mode use cli-tool，当前 Shell 里的所有项目A相关变量被清理干净，然后加载项目B的变量、别名、PATH、甚至 Git 配置。 - 输入
context-mode off，恢复到一个“干净”的状态。
我还希望这个工具足够简单，不依赖任何外部服务，不需要守护进程，不需要安装数据库，甚至可以放进我的 dotfiles 仓库里，换电脑时一条命令就能同步。所以最终我决定自己写一个。
2. context-mode的核心设计：上下文即配置束
2.1 一个上下文包含什么
我给自己定的第一个问题是：什么样的东西算是“上下文”？最终我列了一个清单，分为四类：
- 环境变量：
export JAVA_HOME=/opt/jdk11、export NODE_ENV=production、export DATABASE_URL=... - 路径映射：
PATH的前缀注入，如export PATH=/opt/maven/bin:$PATH - Shell 函数与别名：比如项目B的
debug-server()，项目C的ll别名 - 其他临时配置：比如 Git 仓库当前的
diff工具、错误输出语言、以及挂钩到cd事件的回调
这四种类型共同构成一个“配置束”。每个配置束就是一个上下文。在context-mode的设计里，一个上下文用一个独立的目录/文件来表示，里面存放这些配置。切换上下文时，不是简单执行一段脚本，而是先精确撤销上一个上下文携带的配置，再加载新上下文的配置。
举个具体的例子。项目A的上下文包含：
# context-A/env.sh export JAVA_HOME=/usr/lib/jvm/java-11-openjdk export MAVEN_OPTS="-Dmaven.repo.local=/home/me/.m2-repo-service" export DATABASE_URL="jdbc:postgresql://localhost:5432/service?user=readonly" export GIT_COMMIT_PREFIX="[SVC-"项目B的上下文包含：
# context-B/env.sh export JAVA_HOME="" # 显式清空 export NODE_ENV=development export PATH="/usr/local/bin:/opt/node16/bin:$PATH" unset MAVEN_OPTS注意项目B里我把JAVA_HOME设为空并unset MAVEN_OPTS。这是上下文切换里最微妙的地方：如果你不去“清理”上一个上下文的字段，光靠export新变量是不行的，因为变量仍然存在于环境中，只是被覆盖或者没被覆盖。所以每个上下文定义里，必须声明自己想“清空”或“忽略”哪些字段。
我把这些声明统一放在每个上下文目录下的config.sh里面。用export表示要设置，用unset表示要清除。这样，上下文文件既是定义又是指令。
2.2 为什么选择环境和变量的组合
有人可能会问：为什么不直接用 Docker 容器隔离？每个项目一个容器，环境天然隔离。这听起来很干净，但在日常本地开发里，Docker 太重了。我经常需要修改代码后立即运行测试，需要快速用vim或code打开文件，需要和本地已有的 Git 仓库交互。容器的性能开销还能忍，但“容器内部文件路径”和“宿主机路径”之间的映射关系会带来很多麻烦。比如 vim 的配置、SSH 代理、等等。
也有人问：为什么不直接用 shell 脚本 source 一下就完事？比如：
source ~/contexts/service-api/run.sh这样最大的问题是“没有撤销机制”。当我执行source /home/me/dev/other/run.sh时，上一个脚本设置的变量还在。我需要手动记着上一次设置了哪些变量，然后一个个unset。一旦遗漏，后果就是“上下文污染”。而context-mode的核心价值，恰恰是把“记录并撤销”这个过程自动化。
我选择的环境 + 变量组合方案，本质上是一种“用户态上下文隔离”。它不像容器那样隔离进程和文件系统，但隔离了当前 Shell 的“语义环境”。对于大部分配置类需求，用户态隔离已经足够。它足够快、足够透明，而且允许用户随时查看当前生效的变量，这对于调试非常重要。
注意：如果某个项目真的需要完全隔离的文件系统、网络栈、权限模型，那应该用容器，而不是 context-mode。context-mode 解决的是“轻量切换”问题，而不是“强隔离”问题。
3. 从零实现：目录结构、存储格式与命令设计
3.1 存储结构：一个目录搞定
我的实现思路非常简单：所有上下文都存放在$HOME/.contexts目录下。每个上下文占用一个子目录，目录名就是上下文 ID，比如：
~/.contexts/ ├── default/ # 干净状态 ├── service-api/ # 公司微服务 │ ├── env.sh # 环境变量 │ ├── alias.sh # 别名与函数 │ ├── hooks.sh # 切换时执行的额外脚本 │ ├── paths.sh # PATH 特殊处理 │ └── meta.json # 元数据，比如说明、依赖的Shell ├── cli-tool/ # 开源CLI │ ├── env.sh │ ├── alias.sh │ ├── hooks.sh │ ├── paths.sh │ └── meta.json └──># paths.sh prefix:/opt/maven/bin prefix:/usr/local/bin我会解析这个文件，然后统一计算PATH。为什么不直接在env.sh里修改PATH？因为如果两个上下文都要往PATH前缀加东西，切换时我需要知道哪些部分是上一个上下文加的，哪些是操作系统原本就有的。如果用export PATH=/new:$PATH这种写法，很难精确移除。所以我把PATH的变化单独抽出来管理。
hooks.sh则是给“想跑额外命令”的场景准备的。比如，每次切到 service-api 时，我需要先运行mvn -v检查版本；每次切到>context-mode list # 查看所有可用的上下文 context-mode use <context-id> # 切换到指定上下文 context-mode off # 回到 default（干净状态）
另外我再加了一个辅助命令：
context-mode show # 查看当前生效的上下文和关键变量list会扫描~/.contexts目录下的所有子目录，读取每个meta.json里的description字段，然后打印一张表格：
ID Description ------ ----------------------------- default 空白环境，没有任何额外配置 service-api 公司微服务（Java 11 / Maven 私服） cli-tool 开源命令行工具（Node 16 / npm 官方源）># default context: clean shell切换时，脚本会先“卸载”当前上下文，再“安装”目标上下文。具体实现我会在下一节详细展开。
4. 关键实现细节：符号链接、Shell函数和环境变量注入
4.1 用符号链接而不是改文件
刚开始写这个工具时，我犯了个错误：我想要让上下文“切换”生效，于是尝试直接用sed去修改~/.bashrc或~/.zshrc，比如把source ~/.contexts/service-api/env.sh追加进去。但这样做至少有三个问题：
- 如果你在多个终端窗口之间共享
~/.bashrc，一个终端的切换会搞乱另一个终端的配置。 sed修改文件容易出语法错误，而且很难做幂等。- 每次切换都去编辑配置文件，影响性能，还容易触发 shell 重新加载的意外行为。
后来我想明白了，正确的做法不是修改“全局配置文件”，而是修改当前 Shell 进程的内存环境。也就是说，让context-mode use xxx这个命令在当前 Shell 里source一系列脚本。函数、别名、环境变量都是在当前进程内生效，不影响其他终端。
那么，context-mode这个命令本身怎么做到在当前 Shell 里生效？如果用普通的 bash 脚本执行，子进程里export的变量不会影响到父 Shell。所以必须用 Shell 函数来实现。
我在~/.zshrc里写了这样的函数：
function context-mode() { local cmd="$1" case "$cmd" in use) __cm_switch "$2" ;; off) __cm_switch "default" ;; list) __cm_list ;; show) __cm_show ;; *) echo "usage: context-mode list|use <id>|off|show" ;; esac }真正的业务逻辑放在__cm_switch里。这个方法支持 bash 和 zsh，我用 POSIX 语法写，避免依赖某个 shell 独有的特性。函数名带双下划线，避免和用户自己的函数冲突。
注意：
context-mode不是一个可执行文件，而是一个 Shell 函数。如果你直接写成脚本然后在子进程里运行，那它永远无法切换父进程的环境。这是所有“类环境切换工具”最核心的机制。
那符号链接在哪里用？我在项目里用符号链接来管理那些“跨上下文的固定工具版本”。比如，不同上下文可能需要不同版本的 Node，但我不想在env.sh里写死绝对路径（因为换机器时路径可能变）。所以我维护了~/.contexts/.bin/node16、~/.contexts/.bin/node14这样的目录，里面通过符号链接指向各个版本的实际安装位置。然后在paths.sh里根据需求添加前缀。这样，上下文文件本身不依赖特定机器的绝对路径，只要符号链接指向正确位置即可。
例如，在~/.contexts/.versions/下：
ln -s "$(which node)" ~/.contexts/.versions/node-current ln -s /opt/node16/bin/node ~/.contexts/.versions/node16-bin然后在 cli-tool 的paths.sh里写：
prefix:$HOME/.contexts/.versions/node16-bin这样上下文定义便有了“可迁移性”。我同步 dotfiles 时，只保留符号链接的创建脚本，不保留具体的二进制文件。
4.2 环境变量的注入与清理
环境变量注入的逻辑其实只有三步：快照、导入、回滚。但最难的是“精确回滚”。
我最初做了一个简单版本：切换前把当前所有环境变量快照到一个临时文件，切换后再应用。这样确实能回滚，但会有副作用——比如你在当前 Shell 里临时设置了一个FOO=bar，它也会被快照。当你切到另一个上下文再切回来，这个FOO=bar会“残留”下来，但这可能不是你想要的。更严重的是，快照会把函数、只读变量也当作普通文本记录，回滚时容易出现各种问题。
所以后来我改成了“记录增量”的方式。每个上下文文件里都记录了自己会修改哪些变量。切换离开时，只需要把这些变量恢复成“进入上下文之前”的值。具体实现：我在进入上下文前，先遍历env.sh文件里所有的export和unset，用下面的函数把它们原来的值保存到一个全局关联数组里：
__cm_save_var() { local name="$1" if [[ -z "${__CM_SNAPSHOT[$name]+x}" ]]; then __CM_SNAPSHOT[$name]="${(P)name}" # zsh 写法 fi }然后再执行 source。这样，当退出上下文时，我可以遍历快照表，把变量恢复原状。如果某个变量在上文不存在（即快照里是空标记），我就直接unset。
这个方案的优点是精确、不误伤。缺点是要求env.sh里的写法必须规范：一行一个export或unset，不要写复杂的 shell 逻辑。如果你在env.sh里写if [ ... ]; then export ...; fi，那我这边解析会不准确。我干脆在 README 里明确规范：env.sh 只允许三种语句：
export KEY=valueunset KEY- 空行和注释
这是一个约束，但也是为了保证工具的可靠性。我宁可用约束换确定性，也不愿意用复杂的 eval 整出不可预测的副作用。
4.3 切换时的Hook机制
有些场景下，光是设置变量和别名还不够。比如每次进入项目A时，我需要读取本机最近的一个SSH Agent Socket，然后导出SSH_AUTH_SOCK。这个值可能是动态变化的，不能写死。再比如，每次进入项目B时，我想检查 Git 仓库里是否有未提交修改，有的话就提示一下。
这些侧边动作，最好不要写进env.sh，因为 env.sh 要保持“纯声明”风格。所以我设计了hooks.sh。它的内容就是普通 shell 代码，context-mode会用source加载它。里面可以调用任何外部命令、做条件判断，甚至弹一个notify-send通知。
hooks.sh 的切换触发逻辑是这样的：
__cm_switch进入“卸载旧上下文”阶段时，执行旧上下文hooks.sh里定义的on_exit函数（如果存在）。- “加载新上下文”阶段，执行新上下文
hooks.sh里定义的on_enter函数（如果存在）。
约定就是：
# hooks.sh on_enter() { echo "Entering service-api context" # 检查某个 socket export SSH_AUTH_SOCK=$(ls -t /tmp/ssh-*/agent.* | head -1) } on_exit() { echo "Leaving service-api context" unset SSH_AUTH_SOCK }注意，我在 hooks.sh 里不执行export的全局污染操作，除非明确希望它只在该上下文内有效。实际上，on_enter执行的命令就是当前 Shell 环境的直接操作，所以它export的变量可以影响当前 Shell。但因为退出时会有on_exit来做清理，所以保持了对称性。
使用钩子的好处是，上下文不仅是一个“静态配置集合”，还是一个“行为脚本”。比如项目C每次进入时自动source venv/bin/activate，退出时deactivate，就可以写到 hooks.sh 里。
5. 实测效果与踩坑记录
5.1 在三个项目间来回切换的实测
工具写完后，我用了整整两周。第一周是“试用加修 bug”，第二周开始就是日常主力。我记录了几个典型的切换场景。
场景一：上午在公司仓库开发，我要cd到~/work/service，然后敲context-mode use service-api。执行后，Shell 提示：
[ctx] service-api loaded: JAVA_HOME=/usr/lib/jvm/java-11-openjdk, MAVEN_REPO=service-local, PATH=/opt/maven/bin:...接着我跑mvn compile，一切正常。然后我需要快速查别的项目的代码，但又不想退出当前上下文，因为马上还要回来。这时候我使用另一个终端窗口，在那边cd到另一个目录，使用 context-mode 切到 cli-tool。每个终端是独立的上下文，互不影响。这正是我选择“Shell 函数”而不是“全局文件配置”的好处。
场景二：中午休息后回来，我不记得当前终端在哪个上下文。用context-mode show：
Current context: service-api Last switched: 2025-01-15 11:42 Variables: JAVA_HOME=/usr/lib/jvm/java-11-openjdk MAVEN_OPTS=-Dmaven.repo.local=/home/me/.m2-repo-service一目了然。
场景三：从 cli-tool 切到>export __CM_BASE_PATH="$PATH"
然后paths.sh里的内容不是直接 append，而是由__cm_switch根据__CM_BASE_PATH和新的 prefixes 重新生成PATH。这样每次切换都是“从零构造 PATH”，不会有残留。
第二个坑是关联数组在不同 shell 上的兼容问题。我最初用 bash 的关联数组实现快照，但我的主力 shell 是 zsh，语法不一样。最后我改成了一个兼容性比较好的方法：用一个临时目录里的文件记录快照。虽然性能略低，但兼容性最好。反正每次切换只需要读写十几KB，毫秒级完成。
第三个坑是别名残留。unalias只能移除别名，但如果你在alias.sh里定义了多个别名，再切走时必须逐个unalias。我在__cm_switch里记录了本次上下文里定义的所有别名名字，离开时直接循环unalias $name。注意，有的别名可能原本就被你手动定义过，如果强行 unalias 会把用户自己的配置也去掉。所以我在定义别名时，会先把“该名字旧值”保存到快照，离开时恢复，而不是直接 unalias。这个细节很重要，否则会误伤用户自己的偏好。
第四个坑是 shell 的trap和繁忙环境的兼容性。如果当前 Shell 里已经设置了PS1的 hook，比如使用了zsh-autosuggestions，那我的__cm_switch在处理时可能会触发重绘，提示信息偶尔会被覆盖。最终我选择把提示输出写到 stderr，而不是 stdout。这样即便和某些终端插件有冲突，也不会污染命令替换的输出流。
5.3 经验总结与后续扩展
用了一段时间后，我越来越认同一个观点：工具的复杂度应该被约束在“刚好解决问题”的范围内。context-mode的整个实现只有不到 300 行 shell 代码，但比我去配置 direnv 再花心思处理各种边界情况容易得多。因为它是专门为“手动切换”设计的，没有试图自动感知目录变化，反而少了自动感知带来的误判。
如果以后要继续扩展，我有几个方向想尝试：
- 加一个
context-mode git save，把当前上下文的所有配置文件做成一个 Git 提交，版本化。 - 支持从
~/.zshrc里自动发现已有的 export/alias，一键迁移成上下文配置。 - 允许上下文之间做“继承”，比如定义一个
base-node上下文，其他 node 项目都继承它的NODE_OPTIONS。
但我不打算把它做成一个服务端工具，也不会引入数据库。保持“文件目录 + shell 函数 + 简单约定”这种形态，就是它最大的价值。
如果你也有类似的上下文切换需求，建议先试着抄我这种方式：在~/.contexts里建一个目录，写一个env.sh，再写一个context-mode函数。不要追求复杂，先解决“切换”这一件事。等真正用起来了，你会发现什么功能该加、什么功能不该加，答案会浮出水面。
最后分享一个我在实际使用中总结的小技巧：在~/.zshrc里加上这句：
alias cm='context-mode' alias cm-list='context-mode list' alias cm-show='context-mode show'加上别名后，我的手已经形成了肌肉记忆，cm use service-api成了每天打开终端之后最顺手的动作。这也算是我这个项目最成功的部分——它让自己变得足够简单，简单到让你愿意用它。
