switch-env 是一个统一的多运行时环境管理工具,用于自动识别并切换项目中的 Python / Node.js 运行环境。
项目包含三部分:
switch-env:CLI 主程序(Python)switch-env.plugin.zsh:zsh 自动切换插件install-switch-env.sh:安装/卸载/打包脚本
curl -fsSL https://github.com/ichichuang/switch-env/releases/latest/download/install.sh | AUTO_YES=1 bash说明:
- 使用最新 Release 安装包
AUTO_YES=1表示自动确认安装步骤
- 从 Release 页面下载
switch-env-installer.command - 双击执行(脚本会自动下载最新
switch-env-installer.sh并安装)
如无法双击运行,手动执行:
chmod +x switch-env-installer.command
./switch-env-installer.command安装完成后执行:
source ~/.zshrc或重开终端(推荐)。若通过 curl 安装,也可执行 exec zsh。
安装器会自动识别三种安装模式:
fresh:首次安装(未检测到历史安装痕迹)update:检测到官方安装痕迹,执行更新conflict:检测到同名但非官方文件,默认中止保护你的环境
冲突时如你确认覆盖,使用:
FORCE=1 curl -fsSL https://github.com/ichichuang/switch-env/releases/latest/download/install.sh | AUTO_YES=1 bash调试安装模式评分(排障专用):
DEBUG_INSTALL_MODE=1 QUIET=0 bash ./install-switch-env.sh或统一调试开关(未来兼容):
SWITCH_ENV_DEBUG=1 QUIET=0 bash ./install-switch-env.sh若安装流程已全部成功,但在最后一行出现 @@FILE:switch-env: command not found,原因是旧版单文件安装包在脚本主体结束后仍继续解析后面的内嵌载荷标记行。
请升级到包含该修复的 Release 后重新安装:主安装脚本在正常结束时会 exit 0,不再误执行 @@FILE: 行。
switch-env 支持按项目契约文件 .switch-env 自动切换运行时。
当你 cd 进入项目目录(或其子目录)时,zsh 插件会调用:
switch-env auto --shell --notify并将输出的 shell 命令 eval 到当前会话中。
- Python 决策层会先构建
RuntimePlan(结构化计划对象)。 auto支持两层策略:优先使用.switch-env(契约模式);若不存在契约,会自动从.nvmrc、.node-version、.python-version、pyproject.toml、requirements.txt、environment.yml、package.json等传统标识文件推断并切换(无需在项目中新建文件)。switch-env auto --json:输出结构化 JSON,便于审计与调试。switch-env auto --shell:基于计划渲染 shell-safe 命令,供 plugineval执行。switch-env auto --shell --notify:仅在发生实际切换/激活时输出一行提示(走 stderr,不污染--shell的 stdout,格式含来源from ...)。- 未授权契约时默认安全 no-op:
--shell不输出命令到 stdout,仅在 stderr 提示需先trust。
示例:
switch-env auto --json
switch-env auto --shell
switch-env auto --shell --notify# 仅支持 key=value(严格语法)
python=3.12
node=22
pnpm=8
env_file=.env
post_activate=echo ready- 允许空行、
#开头整行注释 - 仅支持
key=value key必须是[a-z_][a-z0-9_]*value按原始字符串处理,不做 shell 展开- 不允许 inline comment(例如
python=3.12 # comment会报错)
出于安全原因,.switch-env 默认不会自动执行,需先 trust:
switch-env resolve
switch-env trust
switch-env auto --shell取消信任:
switch-env untrust信任基于 sha256(content),当 .switch-env 内容变化时会自动失效,需重新 trust。
command -v switch-env
switch-env doctor
switch-env status说明:
command -v switch-env:确认命令是否在 PATH 中switch-env doctor:检查 pyenv/conda/nvm/node/switch-env 可用性switch-env status:查看当前目录的 Python / Node 匹配状态
| 子命令 | 作用摘要 |
|---|---|
use |
按项目标识切换/激活 Python、Node,可选安装依赖 |
status |
表格展示当前目录 Python / Node 请求与现状 |
doctor |
检查 pyenv/conda/nvm/node/switch-env 与安装态 fresh/update/conflict |
list |
列出 pyenv 版本、conda 环境、nvm 已装 Node |
bootstrap |
检测项目后一次性准备环境(偏「初始化一条龙」) |
deactivate |
去激活 Python / Node(通过 IPC 输出 shell 命令) |
init |
创建或复用虚拟环境,可选装依赖 |
clean |
清理 __pycache__ 或删除指定 venv 目录 |
resolve |
向上查找当前目录生效的 .switch-env 路径 |
trust |
将契约文件按内容哈希记入 ~/.switch-env/allowlist.json |
untrust |
从 allowlist 移除指定契约路径的记录 |
auto |
解析 .switch-env 契约,输出人类可读 / JSON / shell 计划 |
repair |
修复安装态(meta、shebang 等),冲突时保护非官方二进制 |
upgrade |
拉取最新 Release 的 install.sh 并执行升级 |
__hook |
内部/调试:输出 __SWITCH_ENV_CMD__: 风格片段;日常请用 auto --shell |
说明:
- 不带子命令时执行
switch-env会打印帮助并退出(退出码0)。 - zsh 插件提供
se()包装函数(不是简单 alias):se use/se auto会自动补齐--shell --notify,se deactivate会自动补齐--shell。
写在子命令之前,对整条命令生效:
--dry-run:只打印将执行动作,不真正改动环境(具体子命令是否支持以行为为准;trust/untrust写 allowlist 时会跳过写入)--interactive:允许交互确认(如clean删除 venv、use/bootstrap安装步骤)--verbose:输出调试信息;对doctor会打开安装态评分调试输出
示例:
switch-env --verbose doctor
switch-env --dry-run use为保证“执行命令立刻生效”且输出简洁,switch-env 将“给人看的摘要”与“给 shell 执行的命令”分层:
- 默认模式(交互):直接执行
switch-env use会输出简洁彩色摘要(不输出可执行命令片段);通过插件函数执行se use时,会自动走--shell --notify完成切换并显示提示。 - 机器通道(推荐):
--shell模式会在 stdout 输出纯 shell 片段(多行),可直接eval;成功时 stdout 只包含 shell,且不会混入INFO/WARN/OK文本。
示例:
eval "$(switch-env use --shell)"
eval "$(switch-env bootstrap --shell)"
eval "$(switch-env deactivate --shell)"auto --shell:输出项目契约引擎生成的纯 shell 片段(与上面一致,可eval)。auto --json:输出单行 JSON(RuntimePlan),与--shell互斥。
说明:
- 若未加载 zsh 插件,直接执行
switch-env use不会修改父 shell 环境;请改用eval "$(switch-env use --shell)"。 - 旧版 IPC 前缀
__SWITCH_ENV_CMD__:仅用于历史兼容,不建议在新脚本中继续依赖。
为兼顾“可读反馈”和“可管道数据”,switch-env 采用双通道约定:
stdout:数据型输出(如doctor/status/list表格、resolve路径、--shell机器命令片段)stderr:日志与提示(INFO/WARN/OK/ERROR)以及异常信息
这意味着:
switch-env doctor > doctor.out 2> doctor.err时,表格在doctor.out,提示在doctor.err。switch-env use --shell/switch-env auto --shell的stdout保持可eval的纯 shell 内容,不混入日志文本。switch-env use --shell --notify与switch-env auto --shell --notify会将“给人看的提示”输出到stderr,即使外层用$(...)捕获stdout,提示仍会显示在终端,且提示包含来源from ...。
作用:根据项目标识自动切 Python / Node,并按需安装依赖。
常用参数:
--py-manager {pyenv,conda}:强制 Python 管理器-v, --version:强制 Python 版本-e, --env:强制 Conda 环境名--scope {local,global}:pyenv 写入范围(默认local)--no-install:不自动安装缺失版本或依赖--clean-cache:切换后清理缓存--notify:仅在发生实际切换/激活时输出一行提示(stderr,含来源from ...)
示例:
switch-env use
switch-env use --py-manager pyenv -v 3.12 --scope local
switch-env use --py-manager conda -e myenv --no-install立即生效(强烈推荐):
eval "$(switch-env use --shell)"
node -v
which node常见现象与排障(Node 版本未切换):
- 现象:
switch-env use显示目标是v22,但node -v仍是旧版本(如v16)。 - 原因:CLI 运行在子进程,不能直接改父 shell;必须由当前 shell
eval输出片段。 - 处理:
eval "$(switch-env use --shell)"
node -v
which node
type nvm若 type nvm 显示不可用,再手动加载一次后重试:
export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
eval "$(switch-env use --shell)"作用:输出 Python / Node 请求版本、当前版本与匹配状态。
switch-env status作用:诊断 pyenv、conda、nvm、node、PATH 优先级,并输出安装态评分(fresh/update/conflict)。
参数:
- 无子命令专有参数;可使用全局
--verbose查看安装态检测的调试信息(与安装器DEBUG_INSTALL_MODE逻辑对应的 Python 侧评分)。
switch-env doctor
switch-env --verbose doctor典型用途:
- 判断当前安装是否正常(install-mode 是否为
update) - 在升级前确认是否需要先
repair
作用:列出 pyenv 版本、conda 环境、nvm Node 版本。
参数:
--pyenv-only:Python 侧只显示 pyenv 版本表,不显示 conda 环境--conda-only:Python 侧只显示 conda 环境表,不显示 pyenv 版本--python-only:不显示 Node(nvm)段落--node-only:不显示 Python(pyenv/conda)段落
组合说明:默认四类信息按可用性输出。--python-only 会隐藏 Node 列表;--node-only 会隐藏 Python(pyenv/conda)列表。若两者同时指定,则 Python 与 Node 段落均被关闭(通常无输出,属边缘用法)。
示例:
switch-env list
switch-env list --python-only
switch-env list --node-only
switch-env list --pyenv-only
switch-env list --conda-only作用:检测当前目录项目类型后,依次尝试:确保 Python 版本、(在配置允许时)创建/复用 .venv、安装依赖、输出 Node 版本;激活信息通过 __SWITCH_ENV_CMD__: 行打印,需由 shell 插件解析执行。
参数:
--py-manager {pyenv,conda}:覆盖自动选择的 Python 管理器--no-install:跳过依赖安装等步骤(具体跳过范围以实现为准)
示例:
switch-env bootstrap
switch-env bootstrap --py-manager pyenv作用:去激活 Python 环境并恢复 Node 默认版本。
参数:
--runtime {all,python,node}(默认all)
示例:
switch-env deactivate
switch-env deactivate --runtime python作用:在已配置 pyenv 的前提下,于当前目录创建(或复用)指定名称的虚拟环境目录;可选在安装后根据项目文件安装依赖。不做「智能推断用 conda」等分支(与 use/bootstrap 不同)。
参数:
-n, --name:虚拟环境目录名(默认.venv)-i, --install:创建后安装依赖
前置条件:
- 需要
pyenv管理器可用;若不可用会报错。
示例:
switch-env init
switch-env init -n .venv-dev -i作用:删除 Python 缓存,或删除指定虚拟环境目录。
参数:
-n, --name:目标虚拟环境目录名(默认.venv)-c, --cache-only:仅清理缓存,不删虚拟环境
示例:
switch-env clean -c
switch-env clean -n .venv-dev作用:修复 meta/shebang 等安装态问题;如果主程序不是官方版本会拒绝自动修复并给出建议。可使用全局 --verbose 查看安装态评分细节。
switch-env repair
switch-env --verbose repair典型场景:
doctor显示 install-mode 为conflict~/bin/switch-envshebang 被改坏~/.switch-env/meta缺失或损坏
作用:从 GitHub Release latest 下载并执行官方安装器,完成无交互升级。冲突安装态下会先拒绝并提示先 repair。可使用 --verbose 查看升级前后安装态检测输出。
switch-env upgrade
switch-env --verbose upgrade说明:
- 若当前安装态为
conflict,会先阻止升级并提示执行switch-env repair - 升级入口与安装入口一致(统一走
install.shbootstrap) - 升级完成后会再次检测安装态并输出结果
作用:从当前工作目录向上查找第一个存在的 .switch-env 文件,将绝对路径打印到标准输出。
退出码:
0:找到契约文件1:未找到任何.switch-env
switch-env resolve作用:校验并解析目标 .switch-env(严格语法),通过后把「绝对路径 + 内容 sha256 + 时间」写入 ~/.switch-env/allowlist.json。
参数:
path(可选):契约文件路径,或项目目录(若为目录则使用<path>/.switch-env)。省略时从当前目录向上解析,与resolve规则一致。
switch-env trust
switch-env trust /path/to/project
switch-env trust /path/to/project/.switch-env作用:从 allowlist 中移除与给定路径对应的记录(按 file 字段匹配,不要求哈希仍一致)。
参数:
path(可选):同trust。
switch-env untrust
switch-env untrust /path/to/project
switch-env untrust /path/to/project/.switch-env作用:解析已信任的 .switch-env 契约,生成运行时计划。
参数:
--json:输出一行 JSON(RuntimePlan);无契约或未信任时输出action为noop的结构化说明(仍合法 JSON)。--shell:将计划渲染为 shell 脚本片段,供插件或eval;无契约或未信任时标准输出为空,提示信息在标准错误。--json与--shell互斥,同时使用会报错退出。
无附加参数时:人类可读地打印契约路径与键值(不输出 JSON)。
契约键当前行为提示:pnpm 在 v1 仅导出 SWITCH_ENV_TARGET_PNPM;post_activate 仅告警「v1 不执行」,避免任意命令执行风险。
switch-env auto
switch-env auto --json
switch-env auto --shell作用:供旧版插件或调试使用,按项目检测输出 __SWITCH_ENV_CMD__: 形式的激活片段;日常 zsh 自动切换请使用 auto --shell。
参数(实现细节,可能变动):
--ensure--ensure-venv
switch-env __hook --ensure --ensure-venv./install-switch-env.sh
./install-switch-env.sh --build switch-env-installer.sh
./install-switch-env.sh --uninstall
./install-switch-env.sh --help说明:
- 无参数:执行安装流程
--build:构建单文件安装包(带 payload)--uninstall:卸载switch-env
AUTO_YES=1:自动确认QUIET=1:减少输出FORCE=1:冲突场景强制覆盖DEBUG_INSTALL_MODE=1:输出安装模式评分调试信息SWITCH_ENV_DEBUG=1:统一调试开关(兼容未来命令)
示例:
AUTO_YES=1 ./install-switch-env.sh
FORCE=1 AUTO_YES=1 ./install-switch-env.sh
DEBUG_INSTALL_MODE=1 QUIET=0 ./install-switch-env.sh行为:
- 自动下载 latest bootstrap:
install.sh - bootstrap 再下载正式安装器
switch-env-installer.sh并执行 - 显示成功/失败状态并防止窗口闪退
建议排障流程:
switch-env doctor
switch-env repair
switch-env doctor
switch-env upgrade
switch-env doctor解释:
- 第一轮
doctor:确认问题类型 repair:修复安装态异常upgrade:拉齐到最新发布版本- 最后一轮
doctor:确认最终状态
注意:
- 首次运行可能被 macOS Gatekeeper 拦截
- 放行方式:
- Finder 右键
switch-env-installer.command-> 打开 - 系统设置 -> 隐私与安全性 -> 允许执行
- Finder 右键
工作流文件:.github/workflows/release.yml
触发方式:
- 推送 tag:
v*(例如v1.0.0)
发布产物:
install.shswitch-env-installer.shswitch-env-installer.commandsha256.txt
发布步骤:
git add .
git commit -m "release: prepare v1.0.0"
git push
git tag v1.0.0
git push origin v1.0.0核心原则:
- 仓库目录是源码单一真相源:
/Users/cc/MyPorject/switch-env ~/bin是安装产物目录,不直接改源码
建议流程:
- 在仓库改代码
- 运行安装器做本机验证
- 运行
doctor/status验证行为 - 提交与打 tag 发布
- 先执行:
chmod +x switch-env-installer.command ./switch-env-installer.command
- 再检查系统是否拦截(隐私与安全性放行)
- 说明本地已有同名工具,不是官方安装痕迹
- 默认中止是保护机制
- 确认覆盖再用
FORCE=1
- 执行:
source ~/.zshrc
- 或重开终端
- 先用“执行层”方式(推荐):
eval "$(switch-env use --shell)" node -v which node
- 若仍异常,检查 nvm 是否可用:
type nvm - 如未加载,手动加载后再执行:
export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" eval "$(switch-env use --shell)"
- 这通常是“当前版本已匹配”的正常情况:
switch-env判定无需切换就不会重复输出动作提示。 - 可用以下命令确认真实状态:
switch-env status node -v which node
| 症状 | 快速命令 | 结论 | 处理 |
|---|---|---|---|
se use 提示 v22,但 node -v 仍是 v16 |
eval "$(se use --shell)"; node -v; which node |
子进程输出未在当前 shell 执行(se use 默认已带 --notify) |
固定使用 eval "$(se use --shell)" |
eval "$(se use --shell)" 后仍未切换 |
type nvm |
当前 shell 未加载 nvm 函数 | export NVM_DIR=...; source nvm.sh 后重试 |
| 进入目录无切换感知 | switch-env auto --shell |
插件未接管或契约未触发 | 确认 .zshrc 已加载 plugin,重新 source ~/.zshrc |
auto --shell 无输出 |
switch-env resolve |
未找到 .switch-env 或无可切换项 |
补齐契约文件,或检查目录层级 |
auto --shell 只告警不执行 |
switch-env trust && switch-env auto --shell |
契约未信任或内容已变更失信 | 重新 trust 当前契约 |
node/python 包装器偶发失效或行为异常 |
echo "$SWITCH_ENV_EXECUTING" |
锁变量异常残留 | 重新加载插件后重试,升级到最新版本以获得异常安全释放 |
install-switch-env.sh:安装/卸载/打包脚本switch-env:Python CLI 主程序switch-env.plugin.zsh:zsh 插件install.sh:一行安装 bootstrap 入口(支持curl | bash)switch-env-installer.command:双击安装入口.github/workflows/release.yml:tag 自动发布流程.cursor/rules:项目规则文件
本项目采用 MIT License,详见 LICENSE。