技术笔记

主题

npm 命令速查与镜像源配置 ​

1. 全局包管理（最常用） ​

bash
npm list -g --depth=0          # 列出全局安装的包（只看顶层，不展开依赖树）
npm outdated -g --depth=0      # 查看哪些全局包有新版本
npm update -g <package>        # 更新指定全局包到最新
npm update -g                  # 更新所有全局包

说明：

  • --depth=0 控制依赖树展开深度，0 表示只看顶层，避免依赖噪音
  • outdated 输出字段：Current / Wanted / Latest / Location

1.1 真实输出示例（2026-06-13，Mac，用户环境） ​

npm list -g --depth=0 输出：

/Users/admin/.npm-global/lib
├── @anthropic-ai/claude-code@2.1.177
├── @playwright/cli@0.1.14
├── opencode-ai@1.15.12
├── playwright@1.60.0
└── pnpm@10.9.0

npm outdated -g --depth=0 输出：

Package      Current  Wanted  Latest  Location                  Depended by
opencode-ai  1.15.12  1.17.4  1.17.4  node_modules/opencode-ai  global
pnpm         10.9.0   11.6.0  11.6.0  node_modules/pnpm         global

解读：

  • 树状前缀 ├── └── 表示依赖位置，npm-global 在 /Users/admin/.npm-global/lib
  • Wanted = 当前 semver 范围内能升到的最高版本（默认 ^）；Latest = registry 最新 tag
  • 此例 Wanted = Latest，说明没有 major 阻碍，可直接 update

1.2 npm update 的实际行为（踩坑提示） ​

执行 npm update -g opencode（注意包名是 opencode 不是 opencode-ai）后：

up to date in 3s

1 package is looking for funding
  run `npm fund` for details

随后 npm list -g --depth=0 中 opencode-ai 仍显示 1.15.12，未升至 1.17.4。

原因猜测（需进一步验证）：

  • 包名不一致：opencode vs opencode-ai，update 找的是 opencode 包，本机没装所以 "up to date"
  • 全局 update 与 semver 范围限制有关，major 版本可能不自动跨
  • 全局包的 package.json 锁文件行为与项目级不同

安全做法：要升到 Latest，统一用 install 指定版本：

bash
npm install -g opencode-ai@1.17.4
npm install -g pnpm@11.6.0

2. 安装/卸载全局包 ​

bash
npm install -g <package>           # 安装最新稳定版
npm install -g <package>@<version> # 安装指定版本（如 @anthropic-ai/claude-code@1.0.0）
npm install -g <package>@latest    # 显式装 latest tag
npm uninstall -g <package>         # 卸载

3. 项目级依赖 ​

bash
npm install                       # 安装 package.json 中所有依赖
npm install <package>              # 安装到 dependencies
npm install -D <package>           # 安装到 devDependencies
npm install --save-dev <package>   # 等价于 -D

4. Registry 与镜像源 ​

4.1 查看/切换当前 registry ​

bash
npm config get registry                 # 查看当前源
npm config set registry <url>           # 切换源

国内常用镜像：

镜像URL说明
官方源https://registry.npmjs.org/全球默认，国内可能慢
npmmirror（淘宝）https://registry.npmmirror.com/国内首选，同步频率高
腾讯云https://mirrors.cloud.tencent.com/npm/备选

4.2 临时使用指定源（不改配置） ​

bash
npm install -g <pkg> --registry=https://registry.npmjs.org/
npm view <pkg> version --registry=https://registry.npmmirror.com/

注意：临时覆盖 registry 无意义——换源能成功的本质是有可达的镜像，不是有可达的 URL。

5. "registry is unreachable" 报错排查 ​

5.1 报错全文（Claude Code 自检更新时常见） ​

npm error code: ECONNREFUSED
npm error network: request to https://registry.npmjs.org/... failed,
reason: connect ECONNREFUSED ...
• npm registry is unreachable
• Corporate proxy/firewall blocking npm

5.2 排查顺序 ​

1. 测镜像源连通性：
   curl -I https://registry.npmmirror.com/

2. 测官方源连通性：
   curl -I https://registry.npmjs.org/

3. 查看当前 registry：
   npm config get registry

4. 查某个包在当前源是否存在：
   npm view <package> version --registry=https://registry.npmmirror.com/

5.3 三种结局对应处理 ​

结局原因处理
镜像通且包存在源没问题，临时网络抖动重试即可
镜像通但包不存在镜像未同步该包临时 --registry=https://registry.npmjs.org/ 装，或等待同步
镜像都不通公司代理/防火墙配置 HTTPS_PROXY / HTTP_PROXY，或让 IT 开放

5.4 公司代理下的环境变量 ​

bash
export HTTPS_PROXY=http://your-proxy:8080
export HTTP_PROXY=http://your-proxy:8080
# 写到 ~/.zshrc 或 ~/.bash_profile 持久化

6. 禁用 Claude Code 自动更新检查 ​

Claude Code 启动时会探活 npm registry，撞上网络抖动就会报 "registry is unreachable"，但不影响实际使用。如要消除噪音：

bash
export DISABLE_AUTOUPDATER=1

写入 ~/.zshrc（Mac 默认 shell）：

bash
echo 'export DISABLE_AUTOUPDATER=1' >> ~/.zshrc
source ~/.zshrc

7. 验证安装 ​

bash
claude --version       # Claude Code 安装验证
node --version
npm --version