文档 · 指南

国内镜像：magpie 插件、Bun 和更新下载加速

在国内装插件时，npm 和 GitHub 常常很慢，甚至连不上。magpie 可以让这些下载先走国内镜像，镜像上的文件和官方的是同一个，校验方式也一样。

插件页的国内镜像开关

打开插件页。
打开国内镜像开关。之后插件页的下载先问国内镜像，失败再用官方地址。

npm 包（插件包、版本和搜索）：registry.npmmirror.com。
Bun：npmmirror 的二进制镜像。
插件列表：jsDelivr（cdn.jsdelivr.net/gh/magpie-community/plugins）。

镜像还没同步到的文件，会去官方地址下载。npm 的每周下载量仍然显示 npmjs 自己的数字。bun add 也会指向 npmmirror，除非 BUN_CONFIG_REGISTRY 或 NPM_CONFIG_REGISTRY 已经指定了别的源。这个开关不会把任何请求转给 gh-proxy 这类代理。

安装和更新走镜像或代理

安装脚本和 magpie update 都接受 --proxy（http、https、socks5、socks5h，也可以用 MAGPIE_PROXY、HTTPS_PROXY、ALL_PROXY）和 --mirror：一个放在 GitHub 下载地址前面的镜像前缀（也可以用 MAGPIE_MIRROR）。

终端

curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890
magpie update --mirror https://mirror.example/
magpie update mirror https://mirror.example/   # every update, the app's too
magpie update mirror off

在桌面应用里，设置的下载源一栏点使用镜像…，填镜像地址；点不用镜像就改回去。不填就不用任何镜像。如果网络能连 GitHub、连不上 usemagpie.ai，不用设置，更新会自动改从 GitHub 下载并验证签名。

另一种方式默认关闭。设置 MAGPIE_MIRRORS=on 后，magpie 先请求官方源，只有遇到网络错误、HTTP 429、HTTP 5xx 或 GitHub 的限流 403 才改用镜像。默认镜像是 npm 的 registry.npmmirror.com 和 GitHub 的 gh-proxy.com，可以用 MAGPIE_NPM_REGISTRY 和 MAGPIE_GITHUB_MIRROR 换成你自己的：

终端

MAGPIE_MIRRORS=on \
MAGPIE_NPM_REGISTRY=https://registry.example.com \
MAGPIE_GITHUB_MIRROR=https://gh.example magpie serve

官方源和镜像共用一个请求时限，官方源卡住时，总等待时间不会翻倍。

镜像安全吗

magpie 的更新文件，校验和始终来自 usemagpie.ai，不来自镜像；不符的文件不会安装。
Bun 的 zip 按 Bun 官方的 SHA-256 核对；插件包按 npm 给出的 integrity 核对。
带凭据的请求（Authorization、Cookie、API Key、URL 里的令牌）从不走镜像，只发给官方源。
技能的压缩包始终从官方源下载。
npm 的元数据、插件的 README 和搜索结果、版本检查没有校验和，镜像报的版本可能和官方不同。

常见问题

magpie 装插件很慢怎么办？

在插件页打开国内镜像开关。插件列表走 jsDelivr，npm 包和 Bun 走 npmmirror，失败再用官方地址。

magpie 更新下载失败怎么办？

运行 magpie update --mirror <镜像前缀>，或者 magpie update mirror <镜像前缀> 让以后每次更新都走它；也可以加 --proxy 走代理。校验和始终来自 usemagpie.ai。

用镜像会泄露我的 API Key 吗？

不会。带 Authorization、Cookie、API Key 或 URL 令牌的请求从不走镜像，只发给官方源。

MAGPIE_MIRRORS 和国内镜像开关有什么不同？

国内镜像开关让插件页的下载先走国内镜像。MAGPIE_MIRRORS=on 是先请求官方源，遇到网络错误、429、5xx 或 GitHub 限流才用镜像。

相关页面：快速上手、常见错误排查：401、429、502、504 等。遇到问题请到 Discord 提问。