国内安装claude code

最近想体验 Anthropic 官方的命令行工具，结果在安装过程中踩了两个典型的坑。如果你也在 Linux 上遇到了或错误，这篇博客能帮你快速解决。

YuQiao0303

4322人浏览 · 2026-03-19 12:32:25

YuQiao0303 · 2026-03-19 12:32:25 发布

避坑指南：在 Linux 上安全安装 Claude Code CLI

最近想体验 Anthropic 官方的命令行工具 claude-code，结果在安装过程中踩了两个典型的坑。如果你也在 Linux 上遇到了 Region Unavailable 或 EACCES permission denied 错误，这篇博客能帮你快速解决。

❌ 第一坑：官方脚本被地区限制拦截

按照官网文档，
https://code.claude.com/docs/en/quickstart

第一步通常是运行：

curl -fsSL https://claude.ai/install.sh | bash

结果报错：
报错里面含有 App unavailable in region

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html><!-- Last Published: Wed Mar 18 2026 22:03:54 GMT+0000 (Coordinated Universal Time) --><html data-wf-domain="websitemain.claude.com" data-wf-page="68bd5cf2687bfe3893fd2b7f" data-wf-site="6889473510b50328dbb70ae6" data-wf-intellimize-customer-id="117902971" lang="en-US"><head><meta charset="utf-8"/><title>App unavailable in region | Claude</title><link rel="alternate" hrefLang="x-default" href="https://claude.com/app-unavailable-in-region"/><link rel="alternate" hrefLang="en-US" href="https://claude.com/app-unavailable-in-region"/><link rel="alternate" hrefLang="ja-JP" href="https://claude.com/ja-jp/app-unavailable-in-region"/><link rel="alternate" hrefLang="de-DE" href="https://claude.com/de-de/app-unavailable-in-region"/><link rel="alternate" hrefLang="fr-FR" href="https://claude.com/fr-fr/app-unavailable-in-region"/><link rel="alternate" hrefLang="ko-KR" href="https://claude.com/ko-kr/app-unavailable-in-region"/><meta content="Unfortunately, Claude isn't available here." name="description"/><meta content="App unavailable in region | Claude" property="og:title"/><meta content="Unfortunately, Claude isn't available here." property="og:description"/><meta content="https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/68c469d23594abeb9ab6ee48_og-claude-generic.jpg" property="og:image"/><meta content="App unavailable in region | Claude" property="twitter:title"/><meta content="Unfortunately, Claude isn't available here." property="twitter:description"/><meta property="og:type" content="website"/><meta content="summary_large_image" name="twitter:card"/><meta content="width=device-width, initial-scale=1" name="viewport"/><meta content="tPMMBQMBzgZlNmCBal5cMPAx3nhO2iyM4rT9nxuRcdk" name="google-site-verification"/><link href="https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/css/claude-brand.shared.e1c3addac.min.css" rel="stylesheet" type="text/css" integrity="sha384-4cOt2sOCB8umzY27E8CaMtj5IHLMtcRrdxJWvOpV3Q6MjS2oKhU131waB+p1gTXi" crossorigin="anonymous"/><script type="text/javascript">!function(o,c){var n=c.documentElement,t=" w-mod-";n.className+=t+"js",("ontouchstart"in o||o.DocumentTouch&&c instanceof DocumentTouch)&&(n.className+=t+"touch")}(window,document);</script><link href="https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/689f4a9aff1f63fde75cf733_favicon.png" rel="shortcut icon" type="image/x-icon"/><link href="https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/68c33859cc6cd903686c66a2_apple-touch-icon.png" rel="apple-touch-icon"/><link href="https://claude.com/app-unavailable-in-region" rel="canonical"/><style>.anti-flicker, .anti-flicker * {visibility: hidden !important; opacity: 0 !important;}</style><style>[data-wf-hidden-variation], [data-wf-hidden-variation] * {'
curl: (23) Failure writing output to destination

原因分析：
在国内网络环境下，直接访问该脚本会被 Anthropic 服务器拦截，返回一个“此区域不可用”的 HTML 页面，而不是 Shell 脚本。Bash 试图执行 HTML 代码，自然语法报错。

✅ 解决方案：改用 npm 安装
绕过下载脚本，直接通过 Node.js 包管理器安装：

# sudo apt update
# sudo apt install npm
# 如果npm自己就安装很慢，可以尝试以下镜像：
# sudo sed -i 's/archive.ubuntu.com/mirrors.cloud.aliyuncs.com/g' /etc/apt/sources.list
# sudo sed -i 's/security.ubuntu.com/mirrors.cloud.aliyuncs.com/g' /etc/apt/sources.list
npm install -g @anthropic-ai/claude-code

(提示：如果下载慢，可先切换淘宝镜像：npm config set registry https://registry.npmmirror.com)

❌ 第二坑：npm安装时权限不足 (EACCES)

运行 npm 命令后，新的错误出现了：

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied...

原因分析：
默认情况下，npm 试图将全局包安装到系统目录 /usr/local/lib/node_modules。普通用户没有写入该目录的权限。

⚠️ 常见误区：不要直接用 sudo
这个教程
https://github.com/claude-code-chinese/claude-code-guide
不建议加 sudo 说有安全风险：

sudo npm install -g ... # 不推荐！

✅ 最佳实践：配置用户级全局路径
我们将 npm 的全局安装目录修改为用户自己的目录，既安全又无需 sudo。

🛠️ 操作步骤

1. 创建专属目录

mkdir -p ~/.npm-global

2. 配置 npm 使用该目录

npm config set prefix '~/.npm-global'

3. 添加环境变量
编辑你的 shell 配置文件（~/.bashrc 或 ~/.zshrc）：

nano ~/.bashrc  # 或者 nano ~/.zshrc

在文件末尾添加一行，将新目录加入 PATH：

export PATH="$HOME/.npm-global/bin:$PATH"

保存退出（Ctrl+O, Enter, Ctrl+X）。

4. 刷新配置

source ~/.bashrc  # 或者 source ~/.zshrc

5. 重新安装（无需 sudo）

npm install -g @anthropic-ai/claude-code

🎉 验证与额外配置

安装完成后，输入以下命令验证：

claude --version

如果显示版本号，恭喜安装成功！

第三坑：

(⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂) ⠹ idealTree:lib: sill idealTree buildDeps
需要配镜像

第四坑：

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE package: ‘@anthropic-ai/claude-code@2.1.80’,
npm WARN EBADENGINE required: { node: ‘>=18.0.0’ },
npm WARN EBADENGINE current: { node: ‘v12.22.9’, npm: ‘8.5.1’ }
npm WARN EBADENGINE }

⚠️ 问题分析

你的环境：Node.js v12.22.9 (这是 Ubuntu 20.04 等老系统自带的版本，非常旧)。
软件要求：@anthropic-ai/claude-code 明确要求 Node.js >= 18.0.0。
后果：claude-code 使用了大量 ES6+ 的新语法和特性。在 Node 12 下运行，通常会直接报错 SyntaxError: Unexpected token 或 ReferenceError，导致程序根本启动不了。

✅ 解决方案：升级 Node.js 到 LTS 版本

在阿里云上，最稳妥的方法是使用 NVM (Node Version Manager) 来安装新版 Node，这样不会污染系统原有的 Python 或其他依赖。

第 1 步：安装 NVM

复制并运行以下命令（如果提示 curl: command not found，请先运行 sudo apt update && sudo apt install curl -y）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

第 2 步：激活 NVM

安装完成后，需要让配置生效：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

(注：如果是新开的终端窗口，通常会自动生效。如果不确定，可以重启终端或运行 source ~/.bashrc)

第 3 步：安装 Node.js 20 (LTS 长期支持版)

推荐安装 20 版本，既稳定又满足 >=18 的要求：

nvm install 20

第 4 步：切换默认版本

确保以后打开终端都用新版本：

nvm use 20
nvm alias default 20

如果他说
Your user’s .npmrc file (${HOME}/.npmrc)
has a globalconfig and/or a prefix setting, which are incompatible with nvm.
Run nvm use --delete-prefix v20.20.1 to unset it.

就听他的运行这一行即可

第 5 步：验证版本

确认升级成功：

node -v
# 应该输出 v20.x.x
npm -v
# 应该输出 10.x.x

🔄 第 6 步：重新安装 claude-code

既然节点环境变了，建议卸载旧的（虽然可能没装好）并重新安装，以确保二进制文件链接正确：

# 卸载旧版本
npm uninstall -g @anthropic-ai/claude-code

# 重新安装
npm install -g @anthropic-ai/claude-code

这次应该不会再出现 EBADENGINE 警告，且能正常下载所有依赖。

🎉 最终验证

claude --version

如果输出了版本号，现在你可以放心地配置 API Key 并开始使用了！

# 配置环境变量 (示例)
echo 'export ANTHROPIC_API_KEY="sk-xxx"' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"' >> ~/.bashrc
source ~/.bashrc

总结

# 安装npm
apt install update
apt install npm 

# 配置npm安装软件时的路径
mkdir -p ~/.npm-global 
npm config set prefix '~/.npm-global'
vim ~/.bashrc  # 或者 nano ~/.zshrc # 在末尾加上export PATH="$HOME/.npm-global/bin:$PATH"， 保存退出
source ~/.bashrc  # 或者 source ~/.zshrc

# 安装claude code
npm config set registry https://registry.npmmirror.com # 配置镜像，不然网络不行
npm install -g @anthropic-ai/claude-code # 安装

# 验证结果
claude --version

更新一版，包含其他报错的解决

1. 阿里云上APT 更新缓慢 / 无法连接

现象描述：执行 apt-get update 时，进度条长时间卡在 0% 或显示 Connecting to...。
具体报错：

Err:1 http://archive.ubuntu.com/ubuntu focal InRelease
Could not connect to archive.ubuntu.com:80 (91.189.91.39), connection timed out

解决方案：切换到阿里云内网镜像站。

sudo sed -i 's/archive.ubuntu.com/mirrors.cloud.aliyuncs.com/g' /etc/apt/sources.list
sudo apt-get update

2. Node.js 版本不匹配 (Unsupported Engine)

现象描述：安装现代工具（如 Claude Code）时，npm 拒绝安装并弹出警告。
具体报错：

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE package: '@anthropic-ai/claude-code@2.x.x',
npm WARN EBADENGINE required: { node: '>=18.0.0' },
npm WARN EBADENGINE current: { node: 'v12.22.9', npm: '8.5.1' }
npm WARN EBADENGINE }
解决方案：使用 NVM 安装最新的 LTS 版本。
```
nvm install 20
nvm use 20
```

3. GitHub 脚本下载超时 (Connection Refused)

现象描述：执行 curl 安装脚本时，没有任何字节下载，最终报错。
具体报错：

curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused
或 Speed: 0 Time: --:--:-- Error

解决方案：使用国内 Gitee 镜像脚本。

curl -fsSL https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash

4. npm 包安装挂起或权限报错

现象描述：安装包时进度条不动，或者因为使用 sudo 导致后续权限混乱。
具体报错：

npm ERR! code EACCES (权限受限)
npm ERR! syscall rename
network Still extracting... (网络极慢)

解决方案：切换 npm 源并使用 NVM（避免 sudo）。

# 切换镜像源
npm config set registry https://registry.npmmirror.com
# 无需 sudo 安装
npm install -g @anthropic-ai/claude-code

5. NVM 下载 Node 镜像缓慢

现象描述：nvm install 过程中下载 .tar.gz 包速度极慢。

解决方案：在环境变量中指定阿里云的 Node 镜像地址。

# 临时生效
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
# 建议写入 ~/.bashrc 永久生效
echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.bashrc

再次更新：Error: claude native binary not installed.

报错信息：

Error: claude native binary not installed.



Either postinstall did not run (--ignore-scripts, some pnpm configs)

or the platform-native optional dependency was not downloaded

(--omit=optional).



Run the postinstall manually (adjust path for local vs global install):

  node node_modules/@anthropic-ai/claude-

最后解决方法：

# 1. 彻底移除旧包
npm uninstall -g @anthropic-ai/claude-code

# 2. 清理 npm 全局缓存（防止它一直从本地调用坏掉的缓存）
npm cache clean --force

# 3. 重新安装（指定版本）
npm install -g @anthropic-ai/claude-code@2.1.110 --registry=https://registry.npmmirror.com