一条命令看清 npm / pnpm / yarn / bun / pip / uv / go / cargo / composer / gem / nuget 各自在用哪个镜像源, 测速、切换、还原都走同一套逻辑;同一个包还带一个本地图形界面,适合不想记命令的时候点两下。
- 一眼看全:检测 PATH 与配置文件,列出 11 个工具是否安装、版本、当前源来自文件还是环境变量。
- 维护镜像列表:内置 50 条国内常用源,支持添加自己的私有源(写在用户配置里,升级不丢)。
- 一键测速:默认 3 路并发探测,CLI 带进度条;同一 URL 的结果会同步给共用该源的其它工具(npm / pnpm / yarn / bun 一次测完一起亮),遵循
HTTP_PROXY/HTTPS_PROXY/NO_PROXY。 - 安全写入:只改目标键、写前备份
<配置文件>.mirrorhub.bak、临时文件 + rename 原子替换、--dry-run预览。 - CLI 与 GUI 同一个内核,行为不会漂移;GUI 只监听
127.0.0.1,每次启动生成一次性 token。 - 对 agent 友好:
--json输出统一信封,稳定的错误码与退出码,无交互、无颜色也能跑。
# 全局安装(需要 Node.js >= 20.19)
npm install -g @mirrorhub/cli
# 或者不安装,直接跑
npx @mirrorhub/cli ls
# 从源码
git clone https://github.com/Weidows/mirrorhub.git
cd mirrorhub && npm install && npm run build
node dist/index.js ls安装后有两个等价的命令名:mirrorhub 和 mh。不带参数运行 mh 会打开图形界面,同时在终端打印版本、界面地址和常用命令;只想看版本用 mh version。
不想装 Node 也可以直接下载 Releases 里的单文件可执行程序, 解压即用、无运行时依赖:
| 平台 | 文件 |
|---|---|
| Windows x64 | mirrorhub-win32-x64.exe |
| Linux x64 / arm64 | mirrorhub-linux-x64 / mirrorhub-linux-arm64 |
| macOS Intel / Apple Silicon | mirrorhub-darwin-x64 / mirrorhub-darwin-arm64 |
这些文件用 Node SEA(Single Executable Application)打包,再经 UPX 压缩,体积约 27–35 MB; 未压缩时约 90–125 MB(Node 运行时本身就有这么大)。代价是每次启动要先解压,比 npm 安装的版本慢约 0.3 秒。
双击(不带参数)会直接打开图形界面,关掉那个控制台窗口即退出;在终端里带参数运行就是普通 CLI。
高频调用(尤其是给 agent 用)还是建议 npm i -g @mirrorhub/cli,启动只要几十毫秒。
mh ls # 11 个工具现在用什么源
mh test npm # 测一遍 npm 家族的镜像
mh use npm npmmirror # 切到 npmmirror
mh fastest pip --apply # 测速后直接切到最快的 pip 源
mh reset pip # 回到官方源
mh gui # 打开图形界面ls 的输出大致是这样:
工具 版本 镜像 来源 地址
npm 11.19.1 npmmirror 文件 https://registry.npmmirror.com
pnpm 11.7.0 官方源 文件 https://registry.npmjs.org
pip 26.2.1 官方源 默认 https://pypi.org/simple
uv 0.11.19 中科大 环境变量 https://mirrors.ustc.edu.cn/pypi/simple
...
11 个工具 · 9 个已安装 · 2 个已切换到非官方源
提示:环境变量仍优先于配置文件:uv
| 命令 | 说明 |
|---|---|
ls [--installed] |
列出工具、版本、当前镜像与来源;--installed 只看已安装 |
mirrors [工具] |
列出内置与自定义镜像(含 id 与 URL) |
test [工具] [--refresh] |
3 路并发测试可用性与延迟(CLI 显示进度条);结果按 URL 缓存 5 分钟并同步给共用该源的其它工具 |
use <工具> <镜像> |
切换镜像,镜像可写 id、名称或完整 URL |
reset <工具> |
还原官方源,只删自己写的键 |
fastest <工具> [--apply] |
选延迟最低的可用镜像,--apply 直接切换 |
add <工具> --name <名称> --url <地址> [--note <备注>] |
添加自定义镜像 |
rm <工具> <镜像 id> |
删除自定义镜像(内置镜像不可删) |
gui [--port N] [--no-open] |
启动本地图形界面 |
version / help [命令] |
版本与帮助 |
全局选项:-j, --json、-n, --dry-run、--no-color、-v, --verbose、-h, --help。
所有命令加 -j 都会输出同一个信封,成功与失败都只有一层结构:
$ mh ls -j
{"ok":true,"data":{"summary":{"tools":11,"installed":9,"configured":2},"tools":[...]}}
$ mh use npm no-such-mirror -j
{"ok":false,"error":{"code":"unknown_mirror","message":"npm 没有镜像 no-such-mirror","hint":"用 mirrorhub mirrors npm 查看可用镜像"}}- 退出码:
0成功,1运行失败(读写、网络),2用法错误(未知命令/工具/镜像)。 - 错误码:
unknown_tool、unknown_mirror、bad_request、read_failed、write_failed、not_found、no_usable_mirror。 - 修改类命令先加
--dry-run可以拿到完整计划而不写盘;data.dry_run会是true。 - 管道提前关闭(例如
| head)时安静退出,不打印堆栈。
| 工具 | 类别 | 配置文件 | 环境变量(优先) |
|---|---|---|---|
| npm | JavaScript | ~/.npmrc |
NPM_CONFIG_REGISTRY |
| pnpm | JavaScript | ~/.npmrc(与 npm 共用) |
NPM_CONFIG_REGISTRY |
| yarn | JavaScript | ~/.yarnrc.yml(berry)或 ~/.yarnrc(classic) |
— |
| bun | JavaScript | ~/.bunfig.toml |
BUN_CONFIG_REGISTRY |
| pip | Python | %APPDATA%/pip/pip.ini 或 ~/.config/pip/pip.conf |
PIP_INDEX_URL |
| uv | Python | %APPDATA%/uv/uv.toml 或 ~/.config/uv/uv.toml |
UV_INDEX_URL / UV_DEFAULT_INDEX |
| go | Go | go env GOENV 指向的文件 |
GOPROXY |
| cargo | Rust | ~/.cargo/config.toml |
CARGO_HOME |
| composer | PHP | %APPDATA%/Composer/config.json 或 ~/.config/composer/config.json |
COMPOSER_HOME |
| gem | Ruby | ~/.gemrc |
— |
| nuget | .NET | %APPDATA%/NuGet/NuGet.Config |
— |
内置镜像:npm 家族 5 条、pip/uv 各 6 条、go/cargo/composer/gem 各 4 条、nuget 2 条。
环境变量的优先级高于配置文件:如果检测到 origin: "env",use 仍会改文件,但需要你自己处理环境变量,
ls 会在页脚提醒「环境变量仍优先于配置文件」。
mh gui 会在 127.0.0.1 上起一个临时端口并打开浏览器:
- 只监听本机回环地址,不对外暴露;
- 每次启动生成随机 token,所有写操作需要
X-MH-Token,且只接受 POST; - 同一时间只保留一个实例,重复执行
mh gui会复用已打开的窗口; - 页面右上角的「退出」会关闭服务;也可以 Ctrl+C。
--no-open 只起服务不打开浏览器,--port N 固定端口。
- 写入前把原文件复制为
<配置文件>.mirrorhub.bak(只有一个备份,覆盖式)。 - 用同目录临时文件 +
rename原子替换,避免写一半掉电留下坏文件。 - 只增删自己管理的键:npm 的
registry、pip 的index-url/trusted-host、cargo 的[source.mirrorhub]、 nuget 的key="mirrorhub"等;token、私有源、其它配置原样保留。 reset不会恢复「你上次手动改的值」,它只负责把自己写进去的东西删掉,让工具回到官方默认。
npm install
npm run build # tsc -> dist/
npm test # 构建后跑 40 个测试(doc / adapters / service / probe / CLI)
npm run dev -- ls # 用 Node 的类型擦除直接跑 src/index.ts
npm run build:sea # 当前平台的单文件可执行程序 -> build/mirrorhub-<platform>-<arch>构建会先用 scripts/gen-assets.mjs 把 assets/ 里的 html/css/js 生成为 src/gui/assets.gen.ts,
这样 CLI、npm 包和单文件二进制都不依赖外部资源目录。
目录:
src/
catalog.ts 内置镜像数据
registry.ts 11 个工具的元信息(二进制名、版本参数)
manager/ 配置读写:ctx(文件/进程)、doc(行编辑器)、adapters(每工具一个)
probe.ts HTTP(S) 探针(支持 HTTP 代理 CONNECT)
app.ts Service:CLI 与 GUI 共用的唯一入口
userconfig.ts 自定义镜像持久化
cli/ 参数解析、帮助、表格输出、退出码
gui/server.ts 本地 HTTP 服务(界面由 assets.gen.ts 内嵌)
assets/ GUI 的 html/css/js 源文件
scripts/ 界面内嵌 + Node SEA 打包
test/ node:test,跑构建后的 dist
版本号写在 package.json(src/version.ts 与之一致,测试会校验)。发版流程:
npm version patch # 或 minor / major,同时打 tag
git push --follow-tags
gh release create v0.1.1 --title v0.1.1 --notes "..." # 发布 release 即触发工作流.github/workflows/release.yml 在 release 发布后做两件事:
- 在五个原生 runner 上构建单文件二进制(Node SEA 的 V8 blob 与平台绑定,不能交叉编译), 作为 release 附件上传;
- 校验 tag 与
package.json版本一致后执行npm publish。
npm 发布走 Trusted Publishing(OIDC),不需要任何 secret。绑定在 npm 包设置里,字段必须严格一致:
仓库 Weidows/mirrorhub、workflow release.yml、Environment 留空、允许 npm publish。
文件名就是信任契约 —— 改名会让发布立刻 ENEEDAUTH。
ci.yml 在 push / PR 时跑一遍 npm test。