mirror-switcher（镜像切换工具 / Mirror Switcher）

mirror-switcher（镜像切换工具 / Mirror Switcher）

全平台环境镜像源 / 版本切换工具集 --- 命令格式 1:1 复刻 nrm ，统一 switch- 前缀，覆盖前端、后端、Python、容器、Linux 系统、运维常用包管理器源。

A unified mirror-source / version switcher across 20+ ecosystems --- nrm-style CLI, switch- prefix, cross-platform pure-Python (stdlib only).

如果你熟悉 nrm，那么本套件中的 20 个工具你都会用------它们共享同一套命令，仅业务对象不同。每个工具都是跨平台纯 Python（仅依赖标准库），开箱即用。

所有命令行输出与代码注释均为中英文对照。

---

一、为什么需要它 / Why

开发者在不同网络环境下经常需要在「官方源」与「国内镜像源」之间反复切换：nrm 解决了 npm 的痛点，但 pip、brew、docker、maven、go、cargo、yum、apt...... 每一个都要查一遍文档、改一遍配置文件。本套件把这些操作统一起来，命令完全一致：

switch-xxx ls            # 列出全部预设源 / list all preset sources
switch-xxx use tsinghua  # 切到清华源 / switch to Tsinghua mirror
switch-xxx test          # 给所有源测速排序 / latency-test & rank all sources

二、工具清单（共 20 个）/ Tool list (20 in total)

命令 / Command	用途 / Purpose	对标 / Mirrors
switch-npm	npm / pnpm / yarn 包源 / package registry	nrm
switch-node	Node.js 多版本管理 / version manager	nvm（自动识别 fnm / volta / nvm）
switch-brew	macOS Homebrew 镜像 / Homebrew mirror	需求① ibrew
switch-pip	Python pip（PyPI）跨平台源 / cross-platform pip	需求②
switch-conda	Anaconda / Miniconda 通道 / conda channels	需求③
switch-docker	Docker registry 镜像加速器 / registry mirror	需求④
switch-git	Git 克隆加速（GitHub 代理）/ clone acceleration	需求⑤
switch-yum	CentOS / Rocky / Alma YUM 源 / YUM source	需求⑥
switch-apt	Ubuntu / Debian APT 源 / APT source	Linux Debian 系
switch-pacman	Arch / Manjaro Pacman 源 / pacman mirrorlist	Arch 系
switch-dnf	Fedora DNF 源 / DNF source	Fedora
switch-zypper	openSUSE Zypper 源 / Zypper source	SUSE 系
switch-maven	Maven 仓库镜像 / Maven repository	Java 后端
switch-gradle	Gradle 依赖源 / Gradle source	Gradle 项目
switch-go	Go GOPROXY 代理 / Go modules proxy	Golang
switch-cargo	Rust Cargo crates 源 / Cargo crates	Rust
switch-composer	PHP Composer 镜像 / Composer mirror	PHP
switch-nuget	.NET NuGet 程序包源 / NuGet feed	C# / .NET
switch-pub	Flutter / Dart Pub 镜像 / Pub mirror	Flutter
switch-helm	Kubernetes Helm Chart 仓库 / Helm repo	运维 K8s

三、全局通用指令（所有 switch-* 工具通用）/ Shared commands

ls                   列出所有预设与自定义源（* 标记当前生效源）
                     list all preset & custom sources (* = current)
current              查看当前正在使用的源 / show current source
use <name>           切换至指定命名源 / switch to a named source
add <name> <url> [home]   手动添加自定义私有源 / add a custom source
del <name>           删除一条自定义源 / delete a custom source
test [name]          批量测速所有源并按延迟排序（或测单个）
                     latency-test all sources (or a single one)
home <name>          在浏览器打开对应镜像源主页 / open a source's homepage
backup               备份当前原有配置文件 / back up the original config
restore [stamp]      从最新（或指定时间戳）备份还原配置
                     restore from latest (or given timestamp) backup
help                 查看帮助 / show help
-v / --version       查看版本 / show version

switch-node 命令语义按版本管理映射：ls=列版本、use <ver>=切换、add <ver>=安装、del <ver>=卸载、test=验证每个已装版本可运行。

switch-node maps commands to version management: ls=list, use=switch, add=install, del=uninstall, test=verify.

保留的预设名 （不可 add/del）/ Reserved preset names (cannot be added/deleted)：official、tsinghua、aliyun、ustc，部分系统源另有 163。各工具会按该生态实际可用的镜像补齐（详见各工具 ls 输出）。

四、快速开始 / Quick start

方式 A：远程一键安装（推荐）/ Option A: Remote one-line installer (recommended)

无需 git clone，一行命令拉取并安装所有 20 个工具，自动写入 PATH 并提示如何让当前 shell 立即生效：

Linux / macOS（bash / zsh）：

# 国内推荐（Gitee 源，速度快）/ recommended in China (Gitee)
bash <(curl -fsSL https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.sh)

# 或：管道模式（无 TTY）/ or: piped mode (no TTY)



curl -fsSL https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.sh | bash


# 只安装指定工具（逗号分隔）/ install only specific tools



bash <(curl -fsSL .../bootstrap.sh) --tools=npm,pip,yum


# 卸载 / uninstall


`bash <(curl -fsSL .../bootstrap.sh) --uninstall`
`
`

Windows（PowerShell）：

# 国内推荐 / recommended in China
iwr -useb https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.ps1 | iex

# 仅安装指定工具 / specific tools only



& ([scriptblock]::Create((iwr -useb https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.ps1))) --tools=npm,pip


# 卸载 / uninstall


`& ([scriptblock]::Create((iwr -useb `https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.ps1`))) --uninstall`
`
`

远程安装策略 / Strategy ：优先 git clone（可增量更新），失败则下载 tarball / zip。国内环境自动选择 Gitee 源，海外用 GitHub；可设置环境变量 MS_SOURCE=gitee|github|auto 强制选择。

Prefers git clone (incremental), falls back to tarball/zip. Auto-picks Gitee in CN, GitHub abroad; override with MS_SOURCE.

安装后让当前 shell 立即生效 / Make it effective in current shell：

source ~/.zshrc       # zsh
source ~/.bashrc      # bash
source ~/.config/fish/config.fish   # fish
# 或重开一个终端 / or open a new terminal

方式 B：从源码安装 / Option B: From source

git clone https://gitee.com/eword/mirror-switcher.git
cd mirror-switcher

# 一键安装全部 20 个工具 + 自动 PATH / install all + auto PATH



./install.sh


# 只装部分工具 / install only some



./install.sh --tools=npm,pip,yum


# 卸载 / uninstall



./install.sh --uninstall


# 单个工具安装（传统方式）/ single tool (classic)


`cd switch-pip && ./install-link.sh`
`
`

方式 C：直接用 Python 运行 / Option C: Run with Python directly

不想注册全局命令也行 / No global install needed：

python3 switch-pip/switch-pip.py ls
python3 switch-brew/switch-brew.py use tsinghua
python3 switch-npm/switch-npm.py test
python3 main.py                            # 交互式菜单 / interactive menu
python3 main.py switch-go use goproxy.cn   # 直接调度 / dispatch directly

典型用法示例 / Examples

# brew 源操作（语法和 nrm 一模一样）/ brew (same syntax as nrm)
switch-brew ls
switch-brew current
switch-brew use tsinghua
switch-brew use official
switch-brew add mybrew https://my.internal/brew
switch-brew test

# pip 跨平台源 / cross-platform pip



switch-pip ls

switch-pip use aliyun

switch-pip backup          # 备份 ~/.config/pip/pip.conf / back up pip.conf

switch-pip restore         # 还原 / restore


# 多语言 / multi-language ecosystems



switch-go use goproxy.cn

switch-cargo use rsproxy

switch-maven use aliyun

switch-docker use daocloud


# Linux 系统源（需 root，见下方安全说明）/ Linux system sources (need root)


`switch-yum use aliyun`
`
switch-apt use tsinghua`
`
`

五、架构设计 / Architecture

mirror-switcher/
├── main.py                 # 聚合入口：交互菜单 + 直接调度
├── common/                 # 公共库：一套契约，所有工具共享
│   ├── sources.py          # Source 数据类
│   ├── registry.py         # SourceRegistry：ls/current/use/add/del/test/home/backup/restore
│   ├── cli.py              # 命令行解析与分发（1:1 复刻 nrm）
│   ├── config.py           # 用户自定义源持久化（~/.mirror-switcher/）
│   ├── speedtest.py        # 多线程并发测速
│   ├── backup.py           # 配置文件备份 / 还原
│   ├── system.py           # 跨平台系统识别、which
│   ├── runner.py           # 子进程执行、文件读写
│   ├── browser.py          # 打开主页
│   └── logger.py           # 彩色输出 + 双语辅助 bi()
└── switch-*/               # 每个工具一个目录（薄实现：预设 + apply 逻辑）
    ├── switch-*.py
    ├── install-link.sh     # macOS/Linux 一键软链
    └── install-link.ps1    # Windows PowerShell 注册

设计要点 ：把 nrm 的全部交互逻辑（命令解析、测速、备份、自定义源存储、彩色输出）下沉到 common/；每个 switch-xxx 只需声明 预设源 + 如何读取/写入该工具的真实配置 （get_current / apply_source / config_files）。这让新增一个工具通常只需要一个 ~80--150 行的文件。

六、每个工具的内置镜像（速查）/ Built-in mirrors (cheat-sheet)

镜像地址为编写时的常用值；若上游调整，可用 add 自行覆盖。所有工具均内置 official（一键恢复官方源）。

URLs are common values at time of writing; override with add if upstream changes. Every tool ships official to restore the upstream registry in one step.

• switch-npm: official / npmmirror(淘宝) / ustc / huawei / tencent
• switch-pip: official(PyPI) / tsinghua / aliyun / ustc / huawei / tencent
• switch-conda : official / tsinghua / ustc / aliyun（重写 ~/.condarc）
• switch-docker : official / daocloud / dockerproxy / ustc / 163 / baidu（Linux 改 /etc/docker/daemon.json，macOS/Windows 改 Docker Desktop settings.json）
• switch-brew : official / tsinghua / ustc / aliyun（写 HOMEBREW_* 环境变量并由 shell profile 加载）
• switch-git : official / ghproxy / ghfast / kkgithub / gitclone（git config url.<x>.insteadOf）
• switch-yum: official / aliyun / tsinghua / ustc / 163（按 centos/rocky/almalinux 自动选路径）
• switch-apt: official / tsinghua / aliyun / ustc / 163（自动区分 ubuntu / debian 家族）
• switch-pacman : official / tsinghua / ustc / aliyun / 163（置顶 Server = 行）
• switch-dnf: official / tsinghua / ustc / aliyun / 163
• switch-zypper: official / tsinghua / ustc / aliyun / sjtu
• switch-maven : official / aliyun / huawei / tencent（重写 ~/.m2/settings.xml 的 <mirrors>）
• switch-gradle : official / aliyun / huawei / tencent（写 ~/.gradle/init.gradle）
• switch-go : official / goproxy.cn / aliyun / goproxy.io / tencent（go env -w GOPROXY/GOSUMDB）
• switch-cargo : official / rsproxy / tsinghua / ustc / sjtug / aliyun（写 ~/.cargo/config.toml）
• switch-composer : official / aliyun / tencent / huawei（composer config -g 或改 ~/.composer/config.json）
• switch-nuget : official / tsinghua / aliyun / huawei（写 NuGet.Config）
• switch-pub : official / flutter-io.cn / tsinghua / ustc（PUB_HOSTED_URL + FLUTTER_STORAGE_BASE_URL）
• switch-helm : official / bitnami / aliyun / gitlab（管理名为 switch-helm 的 repo）

七、跨平台与权限说明 / Cross-platform & permissions

• 零三方依赖：仅使用 Python 3.7+ 标准库，Windows / macOS / Linux 均可运行。
• Linux 系统源 （yum / apt / pacman / dnf / zypper）与 Docker daemon.json 需要 root。工具会先尝试直接写入，遇权限不足时自动写临时文件并通过 sudo cp 应用；失败则打印精确命令由你手动执行。
• 备份优先 ：改动系统级配置前，强烈建议先 switch-xxx backup。备份存放在 ~/.mirror-switcher/backups/<tool>/<时间戳>/，可用 switch-xxx restore 还原。
• macOS Homebrew / Flutter ：通过在 shell profile 中插入带标记的 source 行 加载 mirror.sh，多次 use 幂等，不会污染 profile。

七.5、全局 PATH 自动注入 / Auto PATH injection

install.sh / install-link.sh / bootstrap.sh（以及 Windows 的 install-link.ps1 / bootstrap.ps1）会自动：

1. 把 ~/.local/bin（Linux/macOS）或 %USERPROFILE%\bin（Windows）幂等写入 rc 文件 / 注册表；
2. 用 # >>> mirror-switcher PATH >>> / # <<< mirror-switcher PATH <<< 标记块包裹，重复运行不会污染 rc 文件；
3. 在结束时打印 source 命令让当前 shell 立即生效。

支持的 rc 文件 / Supported rc files：

• Linux/macOS：.zshrc、.bashrc、.bash_profile、.profile、.kshrc、.tcshrc、.cshrc、.config/fish/config.fish
• 若以 root 运行：额外写入 /etc/profile.d/mirror-switcher.sh（系统级，所有用户生效）
• Windows：用户级 PATH 注册表项 + 当前 PowerShell 会话立即生效

想完全清理 PATH 块时，删除 rc 文件中两个标记之间的行即可。

To fully clean the PATH block, delete the lines between the two markers in your rc file.

七.6、国产操作系统适配 / Domestic-OS support

本套件已针对国产/中文发行版做了完整识别与适配，所有 Linux 工具都会先调用 linux_distro_family() 自动归类，并显示检测到的发行版：

发行版 / Distro	家族归类 / Family	推荐工具 / Use tool
麒麟 Kylin 桌面/服务器（含银河麒麟、openKylin）	debian（桌面）/ rhel（服务器）	switch-apt（桌面） / switch-yum / switch-dnf（服务器）
统信 UOS（含家庭版、专业版、服务器版）	debian / rhel	switch-apt（桌面） / switch-yum（服务器）
Deepin 深度	debian	switch-apt
openEuler 开源欧拉	rhel	switch-yum / switch-dnf
Asianux（中标麒麟）	rhel	switch-yum
CentOS / Rocky / Alma / RHEL / Oracle	rhel	switch-yum / switch-dnf
Ubuntu / Debian / Mint / Kali / Raspbian	debian / ubuntu	switch-apt
Fedora	fedora	switch-dnf
openSUSE / SLES	suse	switch-zypper
Arch / Manjaro / SteamOS	arch	switch-pacman
Alpine	alpine	（自行用 add 添加源）

识别机制 / Detection ：读取 /etc/os-release 的 ID 与 ID_LIKE 字段；显式主 ID 优先，避免被过于宽泛的 ID_LIKE 误判（如某些 Fedora 镜像错误地写了 ID_LIKE=debian）。

# 在麒麟桌面 V10 上 / on Kylin V10 Desktop:
$ switch-apt use tsinghua
检测到系统 / detected: Kylin V10 SP1
完成后请执行：sudo apt update / after switching run: sudo apt update

# 在 openEuler 22.03 上 / on openEuler 22.03:


`$ switch-yum use aliyun`
`
检测到系统 / detected: openEuler 22.03 LTS`
`
完成后请执行：sudo yum makecache / after switching run: sudo yum makecache`
`
`

八、用户数据存放位置 / User data location

• 自定义源、备份：~/.mirror-switcher/（custom/、backups/、brew/mirror.sh、pub/mirror.sh）
• 该目录在用户主目录下，不会写入仓库目录，安全可删。

九、推送到 Gitee / Push to Gitee

git add .
git commit -m "init: 项目初始化，遵循 switch- 前缀命名，完全对齐 nrm 命令格式"
git push origin main

十、许可 / License

MIT © 2026 Eword eword@139.com