# version-manager **Repository Path**: moqsien/version-manager ## Basic Information - **Project Name**: version-manager - **Description**: 本仓库仅仅为被动同步仓库。 请前往https://github.com/gvcgo/version-manager查看详情。 - **Primary Language**: Go - **License**: MIT - **Default Branch**: main - **Homepage**: https://github.com/gvcgo/version-manager - **GVP Project**: No ## Statistics - **Stars**: 31 - **Forks**: 1 - **Created**: 2024-04-04 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: 版本管理器 ## README

vmr

# vmr · 跨平台 SDK 版本管理器 [English](README.md) | 简体中文 `vmr` 帮你把开发工具的多套版本装在一台机器上,并随时切换到需要的那一套:Go、Node.js、Python、JDK、Rust、Lua…… 一条命令装、切、卸,不需要管理员权限,也不会污染系统目录。 - **多版本共存**:同一个 SDK 可以同时装很多版本,切换只是换一个软链接。 - **项目级锁定**:进项目目录自动切到项目需要的版本,离开自动还原。 - **会话隔离**:临时用某个版本跑一条命令或开一个子 shell,退出即恢复。 - **一条命令迁移新机器**:导出已装版本清单,在新机器上批量装回。 - **能装任意 conda-forge 包**:内置 pixi 的安装能力,不需要预装 conda/miniconda。 - **下载走多线程**:支持校验和、反向代理、本地代理与 `HTTP(S)_PROXY`。 支持 Linux / macOS / Windows,x86_64 与 aarch64 均有预编译包。 ## 演示 ![vmr 演示](vmr/docs/demo.gif) 演示由 [VHS](https://github.com/charmbracelet/vhs) 根据 [`vmr/docs/demo.tape`](vmr/docs/demo.tape) 录制生成。 ## 安装 ### 1. Homebrew(macOS / Linux) ```bash brew install gvcgo/tap/vmr ``` 公式直接使用各平台的预编译包,不在本地编译。Homebrew 只提供 `vmr` 可执行文件,各 SDK 的版本仍由 vmr 自己装到 `~/.vmr` 下。 ### 2. MacPorts(macOS) MacPorts 没有 Homebrew tap 那样的第三方仓库机制,因此 vmr 维护了一个独立的 port source。添加一次后即可安装: ```bash sudo mkdir -p /opt/local/var/macports/sources/github.com/gvcgo sudo git clone https://github.com/gvcgo/vmr-macports \ /opt/local/var/macports/sources/github.com/gvcgo/vmr-macports echo "file:///opt/local/var/macports/sources/github.com/gvcgo/vmr-macports [nosync]" \ | sudo tee -a /opt/local/etc/macports/sources.conf sudo portindex /opt/local/var/macports/sources/github.com/gvcgo/vmr-macports sudo port install vmr ``` 该 port 使用与 Homebrew、Release 包相同的预编译二进制,不在本地编译。如果你的 MacPorts 前缀不是 `/opt/local`,请自行替换。后续升级: ```bash sudo git -C /opt/local/var/macports/sources/github.com/gvcgo/vmr-macports pull sudo portindex /opt/local/var/macports/sources/github.com/gvcgo/vmr-macports sudo port upgrade vmr ``` 详见 [vmr-macports](https://github.com/gvcgo/vmr-macports)。 ### 3. Scoop(Windows) ```powershell scoop bucket add gvcgo https://github.com/gvcgo/scoop-bucket scoop install gvcgo/vmr ``` ### 4. APT(Debian / Ubuntu) ```bash curl -fsSL https://gvcgo.github.io/vmr-apt/vmr.gpg \ | sudo gpg --dearmor -o /usr/share/keyrings/vmr.gpg echo "deb [signed-by=/usr/share/keyrings/vmr.gpg] https://gvcgo.github.io/vmr-apt stable main" \ | sudo tee /etc/apt/sources.list.d/vmr.list sudo apt update sudo apt install vmr ``` ### 5. pacman(Arch Linux) ```bash curl -fsSLO https://gvcgo.github.io/vmr-pacman/vmr.gpg sudo pacman-key --add vmr.gpg sudo pacman-key --lsign-key C387E9AE5C936248D446868C44E5A0323545E858 ``` 把仓库追加到 `/etc/pacman.conf`: ```ini [vmr] SigLevel = Required DatabaseOptional Server = https://gvcgo.github.io/vmr-pacman/$arch ``` 然后安装: ```bash sudo pacman -Syu vmr ``` ### 6. Cargo(源码安装) 需要 Rust 1.85+ 和 C 工具链(macOS 安装 Xcode Command Line Tools,Windows 安装 MSVC Build Tools,Linux 安装 `build-essential` 与 `pkg-config`)。workspace 位于 `vmr/` 下,因此先克隆仓库,再安装 `vmr-cli`: ```bash git clone https://github.com/gvcgo/version-manager cd version-manager cargo install --path vmr/crates/vmr-cli --locked ``` `vmr` 会安装到 `~/.cargo/bin`,请确保该目录在 `PATH` 中。更新代码后重新执行并加 `--force`: ```bash cargo install --path vmr/crates/vmr-cli --locked --force ``` 这些 crate 尚未发布到 crates.io,因此暂不支持 `cargo install vmr`。 ### 7. 下载 到 [Releases](https://github.com/gvcgo/version-manager/releases) 下载对应平台的包: | 平台 | 包名示例 | |---|---| | macOS (Apple 芯片) | `vmr-aarch64-apple-darwin.tar.xz` | | macOS (Intel) | `vmr-x86_64-apple-darwin.tar.xz` | | Linux (x86_64) | `vmr-x86_64-unknown-linux-gnu.tar.xz` | | Linux (ARM64) | `vmr-aarch64-unknown-linux-gnu.tar.xz` | | Windows (x64) | `vmr-x86_64-pc-windows-msvc.zip` | | Windows (ARM64) | `vmr-aarch64-pc-windows-msvc.zip` | ### 8. 解压并放到 PATH Linux / macOS: ```bash tar -xJf vmr-x86_64-apple-darwin.tar.xz mkdir -p ~/.local/bin install -m 755 vmr-x86_64-apple-darwin/vmr ~/.local/bin/vmr # 确保 ~/.local/bin 在 PATH 中 ``` Windows:解压后把 `vmr.exe` 放到任意已在 `PATH` 里的目录。 ### 9. 校验(可选) 每个包都附带 `.sha256` 文件,Release 页面还有汇总的 `SHA256SUMS`: ```bash shasum -a 256 -c vmr-x86_64-apple-darwin.tar.xz.sha256 ``` ### 10. 确认安装 ```bash vmr version ``` ## 接入 Shell 首次以交互方式运行 vmr 时,如果没有检测到当前 shell 的集成配置,vmr 会提示是否自动写入下面 这一行,并回显写入的配置文件与内容。 安装完成后,把下面这一行加到你的 shell 配置里(`~/.zshrc`、`~/.bashrc`、`~/.config/fish/config.fish`): ```bash # zsh eval "$(vmr init zsh)" ``` ```bash # bash eval "$(vmr init bash)" ``` ```fish # fish vmr init fish | source ``` ```powershell # Windows PowerShell:在 $PROFILE 中加入 Invoke-Expression (& vmr init powershell) ``` 这一行会做三件事: 1. 把 vmr 维护的环境变量(`PATH`、`GOROOT` 等)注入当前 shell; 2. 注册 `cd` 钩子,进入带版本锁定的项目目录时自动切换; 3. 定义 `vmr` 包装函数 —— 执行 `vmr use` / `vmr uninstall` 之后,**当前窗口立即生效**,不用再开新终端。 未执行 `vmr init` 也能用命令,只是每次切换版本后需要新开终端。 Windows 下全局环境不走 `vmr.sh`:非 PATH 变量(如 `GOROOT`)写入注册表 `HKCU\Environment`; `PATH` 中**只有一条** `%USERPROFILE%\.vmr\bin`(shim 目录)。`vmr use` 会在该目录为当前 SDK 的每个可执行文件生成 shim(`vmr.exe` 的硬链接,`.cmd`/`.bat` 则生成包装脚本),shim 只在启动 子进程时注入对应前缀的 `PATH`。因此安装任意数量的 SDK 或 conda-forge 包都不会把 `PATH` 撑到 Windows 的 32767 字符上限。 ### 从 0.7.x 升级到 0.8.x - 新版 vmr 启动时会检测 `$HOME/.vmr/vmr`(Windows 为 `vmr.exe`)中由旧版自安装的二进制并提示删除;同时移除 `$HOME/.vmr/vmr.sh`(`vmr.fish`)中旧版的 cd hook 代码,把旧版写入的 `~`/绝对家目录路径改写为当前的 `"$HOME/..."` 形式,保留 SDK 相关配置。 - 删除 PowerShell `$PROFILE` 中由旧版 vmr 写入的非 SDK 相关环境变量和函数,改为使用上面的初始化命令。 - 删除 `~/.zshrc`、`~/.bashrc` 等 shell 配置文件中的旧版 vmr 相关代码,改为添加上面对应 shell 的 `vmr init` 初始化命令。PowerShell 用户也应在 `$PROFILE` 中使用上面的初始化命令。 - 重新打开终端,使新的 shell 配置生效。 ## 快速上手 ```bash vmr plugins # 看看支持哪些 SDK vmr search go # 列出当前平台可装的 Go 版本 vmr use go@1.22.0 # 安装并切换 vmr local go # 查看已装版本, 标记当前生效的 vmr uninstall go@1.22.0 # 卸载指定版本 vmr uninstall go@all # 卸载这个 SDK 的所有版本 ``` `vmr search` 的结果来自插件实时抓取,第一次查询会联网;加 `-n` 可忽略本地缓存重新拉取。 编写插件请参考 [Lua 插件 API 文档](vmr/docs/plugin-api.zh-CN.md)(English: [plugin-api.md](vmr/docs/plugin-api.md))。 ## 常用命令 | 命令 | 别名 | 说明 | |---|---|---| | `vmr version` | `v` | 显示版本 | | `vmr init [shell]` | | 输出 shell 集成脚本 | | `vmr plugins [-u]` | | 列出支持的 SDK;`-u` 先更新插件包 | | `vmr search ` | `s` | 列出可安装版本,`-p` 走 conda-forge 源,`-n` 忽略缓存 | | `vmr use @` | `u` / `h` | 安装并切换(默认全局) | | `vmr use -s ...` | | 仅对本次会话生效 | | `vmr use -l ...` | | 写入项目 `.vmr.lock` 并进入新会话 | | `vmr use -p ...` | | 安装任意 conda-forge 包 | | `vmr use -f ` | | 按清单批量安装 | | `vmr local [sdk]` | `l` | 已装版本列表;`-c` 只显示当前版本 | | `vmr freeze [file]` | `fz` | 导出已装版本清单 | | `vmr migrate [MAP] --asdf` / `--vfox` / `--system` | | 从 asdf / vfox / 系统命令收集版本,生成 `migration_from_*.txt` 清单;不执行任何安装。`MAP` 为可选的 `<来源名> ` 映射文件(样本见 `docs/migration_map/`) | | `vmr uninstall @` | `uni` / `r` | 卸载,`@all` 卸载全部版本 | | `vmr cdhook` | `cd-hook` | cd 钩子内部调用:读取 `.vmr.lock`,提示安装缺失的锁定版本,并注入环境(钩子把项目缓存在 `VMR_CD_CACHE` 中,同一项目内不再重复查找) | | `vmr session` | `se` | 查询当前 shell 是否处于 vmr 会话中 | | `vmr nested` | `ns` | 允许 / 禁止嵌套会话 | | `vmr doctor` | | 只读诊断 shell 集成、环境变量、`PATH` 和版本链接(`--json`、`--quiet`、`--strict`) | | `vmr mcp` | | 以 stdio 方式提供 MCP 服务,供 AI 客户端调用 | ## 项目级版本锁定 想让某个仓库固定使用特定版本,在项目根目录执行一次: ```bash cd my-project vmr use -l node@20.11.0 ``` 这会: - 在项目根目录写入 `.vmr.lock`(记录本项目需要的 SDK 与版本); - 因为执行了 shell 集成,之后每次 `cd` 进这个目录,`cdhook` 会自动切到锁定版本; - `.vmr.lock` 每个项目只查找一次:钩子把解析出的项目目录缓存在 `VMR_CD_CACHE` 中,项目内部切换目录不再重复查找(切换到其他目录时会重新查找); - 如果锁定版本尚未安装,`cdhook` 会列出并询问是否安装;拒绝则跳过安装; - 离开目录后由 shell 钩子还原。 `.vmr.lock` 建议提交到仓库,团队成员 `cd` 进去就自动对齐版本。 ## 会话模式 临时用某个版本跑命令,不影响全局设置: ```bash vmr use -s python@3.12.2 # 退出该子 shell 后自动恢复 ``` 适合「我只想在这个终端里试一下新版本」的场景。若在会话中再想开一层会话,需要先 `vmr nested` 放行。 ## 备份与迁移 ```bash vmr freeze # 导出,默认生成 vmr_20260101.txt vmr use -f vmr_20260101.txt # 在新机器上批量装回 ``` 清单是纯文本,一行一个 `sdk@version`,`#` 开头为注释。每个 SDK 的当前版本写在最后,所以批量装完后生效版本与导出时一致。 ## 从 asdf / vfox / 系统迁移 ```bash vmr migrate --asdf # 读取 ~/.asdf,生成 migration_from_asdf.txt vmr migrate --vfox # 读取 ~/.vfox(或 ~/.version-fox),生成 migration_from_vfox.txt vmr migrate --system # 扫描 PATH 上的常见 SDK 命令,生成 migration_from_system.txt vmr use -f migration_from_asdf.txt ``` 三种迁移都完全只读:不安装任何东西,不写对方的目录,只生成清单。asdf 的状态来自 `$ASDF_DATA_DIR`(默认 `~/.asdf`);vfox 来自 `$VFOX_HOME` 或用户目录,并遵循 `storage.sdkPath`;`--system` 运行常见命令(`node`、`go`、`python`、`bun`、`deno`、`rust`、 `clang`、`gcc`、`ruby`、`java` 等)的版本参数,每个命令只取 PATH 上的第一个可执行文件,并跳过 位于 vmr、asdf、vfox、nvm、fnm、volta、pyenv、rbenv、sdkman、mise、conda 目录下的程序。 `ref:` 构建、未完成的安装、没有运行时负载的版本目录都会被跳过。常见插件名会做映射 (`nodejs` → `node`、`golang` → `go`、`postgres` → `postgresql`、`java` → `jdk`、 `dotnet-core` → `dotnet`);vmr 没有对应插件的 SDK 只在报告中列出,不会猜测。全局解析出的 版本写在每个 SDK 的最后,回放后停在它上面。项目级版本文件暂不转换。 可选的位置参数 `MAP` 用来指定名称映射文件,一旦传入就以它为准:未列出的名称会被跳过并报告。 每行一个 `<来源名> `;只写名称或以 `-` 作为目标表示跳过该来源。根据当前插件包生成的样本见 [`docs/migration_map/`](docs/migration_map/):`asdf.migration.map.txt`、`vfox.migration.map.txt`、 `system.migration.map.txt`(`--system` 使用命令名 → SDK 的映射)。 ## 安装任意 conda-forge 包 vmr 内置 pixi 的安装能力,因此除了插件里的 SDK,也能直接装 conda-forge 上的包: ```bash vmr search -p lua # 从 conda-forge 查询 vmr use -p lua@5.4.6 # 安装 ``` 和插件安装一样,`vmr use -p` 会暴露前缀的可执行文件(Linux/macOS 把 `bin` 加入 `PATH`; Windows 为每个可执行文件生成 shim,不往注册表 `PATH` 里逐条追加),配合 `vmr init` 立即在 当前终端生效。包自带的 `etc/conda/activate.d` 脚本设置的变量不会导入。 默认频道是 `https://conda.anaconda.org/conda-forge`,可用环境变量换成镜像: ```bash export VMR_PIXI_CHANNEL=https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge vmr search -p lua ``` ## 配置 配置文件在 `~/.vmr/conf.toml`;该文件不存在时改读 `~/.config/vmr/conf.toml`。两份不会合并, 写回落到实际读到的那份(两份都不存在时创建 `~/.vmr/conf.toml`)。键名为 PascalCase: | 键 | 说明 | |---|---| | `ProxyUri` | 本地代理,如 `http://127.0.0.1:7890` | | `ReverseProxy` | 反向代理前缀 | | `SDKIntallationDir` | 版本安装目录(注意键名拼写如此) | | `VersionHostUrl` | 版本元数据服务地址 | | `ThreadNum` | 下载线程数 | | `AllowNestedSessions` | 是否允许嵌套会话 | | `GithubToken` | GitHub API Token | | `CacheRetentionTime` | 缓存保留秒数 | | `DisableCache` | 关闭缓存 | 常用环境变量(优先级高于配置文件): | 变量 | 说明 | |---|---| | `VMR_SDK_INSTALLATION_DIR` | 版本与缓存根目录 | | `VMR_HOST` | 版本元数据服务地址 | | `VMR_LOCAL_PROXY` | 本地代理 | | `VMR_REVERSE_PROXY` | 反向代理前缀 | | `VMR_DOWNLOAD_THREADS` | 下载线程数 | | `VMR_ALLOW_NESTED_SESSIONS` | 允许嵌套会话 | | `VMR_PIXI_CHANNEL` | conda-forge 频道(支持镜像) | | `VMR_GITHUB_TOKEN` | GitHub Token,未设置时回退到 `GITHUB_TOKEN` | | `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 标准代理变量,直接生效 | GitHub API 在三个来源都为空时以匿名身份请求,每小时 60 次,只够刷新少量 SDK 的版本列表;装得多建议配一个 Token。 ## 数据都放在哪 ``` ~/.vmr/ ├── conf.toml # 配置 ├── vmr.sh / vmr.fish # 动态环境变量(PATH、GOROOT 等) ├── env_keys.txt # 刷新前需要清掉的非 PATH 变量 ├── bin/ # Windows shim 目录(PATH 唯一入口) ├── shims.json # Windows shim → 真实可执行文件的映射 ├── plugins/ # SDK 版本插件(首次使用自动下载) ├── cache/ # 版本列表与安装包缓存 └── versions/ └── _versions/ ├── -/ # 实际安装目录 └── # 指向当前版本 ``` 想放到别的磁盘,设置 `VMR_SDK_INSTALLATION_DIR` 即可。 Windows 上,全局环境变量写入注册表 `HKCU\Environment` 并广播变更;`PATH` 只保留 `%USERPROFILE%\.vmr\bin` 一条,SDK 命令由 `bin/` 下的 shim 提供,所以 `vmr init powershell` 之外不需要额外修改系统设置。 ## 卸载 vmr ```bash vmr uninstall @all # 先清掉不需要的 SDK 版本 rm -rf ~/.vmr # 再删除配置、缓存与剩余版本 # 最后把 shell 配置里那行 eval "$(vmr init ...)" 删掉 ``` Windows 删除 `%USERPROFILE%\.vmr` 目录,并从 `PATH` 中移除 `vmr.exe` 所在目录和 `%USERPROFILE%\.vmr\bin`(shim 目录)。 ## 常见问题 **`vmr: command not found`** 可执行文件没进 `PATH`。确认 `which vmr`(Windows 用 `where vmr`)能找到。 **切换了版本,当前终端还是旧的** 没有执行 `vmr init`,或者用了 `command vmr` 绕过了包装函数。补上 shell 集成后重开终端。 **`vmr search` 报限流** GitHub 匿名请求每小时 60 次。配置 `GithubToken` 或环境变量 `VMR_GITHUB_TOKEN`。 **下载很慢 / 连不上** 先设 `HTTP_PROXY` / `HTTPS_PROXY`;只代理 vmr 时用 `VMR_LOCAL_PROXY`;conda-forge 走镜像用 `VMR_PIXI_CHANNEL`。 **想重新拉版本列表** `vmr search -n`,或删掉 `~/.vmr/cache/` 后重试。 **会话里再执行 `vmr use` 报错** 默认禁止嵌套会话:先 `vmr nested` 放行,或退出当前会话。 **升级 vmr 本身** 下载新版本的包覆盖旧二进制即可,`~/.vmr` 下的版本与配置不受影响。 ## 反馈 - 问题与建议:[Issues](https://github.com/gvcgo/version-manager/issues) - 版本下载:[Releases](https://github.com/gvcgo/version-manager/releases) - 实现与开发说明见 [vmr/readme.md](vmr/readme.md) ## Star 走势 [![Star History Chart](https://api.star-history.com/svg?repos=gvcgo/version-manager&type=Date)](https://star-history.com/#gvcgo/version-manager&Date)