什么是原生安装?
Claude Code 从基于 Node.js 的应用转变为单一的自包含可执行文件
无需 Node.js
不再需要安装 Node.js 和 npm,降低了入门门槛,避免了版本兼容问题。
单一可执行文件
使用 Bun 编译成自包含的原生二进制文件,包含完整运行时,无需任何外部依赖。
启动速度快 4 倍
基于 JavaScriptCore 引擎,优先优化启动时间和内存占用,特别适合 CLI 工具。
稳定的自动更新
改进的自动更新机制,后台下载安装,无需手动干预。
全平台支持
支持 macOS、Linux、Windows(WSL/Git Bash),一次编译,到处运行。
更安全可靠
避免 npm 权限问题和安全风险,提供更稳定的运行环境。
技术实现:从 TypeScript 到原生二进制
使用 Bun 将 TypeScript 代码编译成单一可执行文件
编译过程
- 转译 TypeScript:将 TypeScript 代码转译成 JavaScript
- 字节码编译:使用
--bytecode标志预编译成 JavaScriptCore 字节码 - 打包依赖:将所有 npm 包和代码打包进来
- 嵌入运行时:将完整的 Bun 运行时(基于 JavaScriptCore)一起打包
- 生成二进制:输出平台原生的自包含可执行文件
# 使用 Bun 编译成单一可执行文件
bun build --compile --bytecode ./src/index.ts --outfile claude
# 生成的文件是完全自包含的
./claude --version
系统要求
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS 10.15+、Ubuntu 20.04+/Debian 10+、Windows 10+(WSL 1/2 或 Git for Windows) |
| 硬件 | 至少 4GB RAM(推荐 8GB+) |
| 网络 | 需要互联网连接(用于 API 调用和更新) |
| Shell | Bash、Zsh 或 Fish(效果最佳) |
| Node.js | ❌ 不再需要(原生安装) |
安装指南
选择适合你的操作系统的安装方式
一键安装(推荐)
curl -fsSL https://claude.ai/install.sh | bash
安装特定版本
# 安装最新版本
curl -fsSL https://claude.ai/install.sh | bash -s latest
# 安装指定版本号
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
验证安装
# 查看版本号
claude --version
# 测试运行
claude "Hello, Claude!"
使用 Homebrew 安装
brew install --cask claude-code
优势:可以通过 brew upgrade 统一管理所有应用的更新。
更新 Claude Code
# 更新 Homebrew
brew update
# 升级 Claude Code
brew upgrade --cask claude-code
⚠️ 前置要求:安装 Git Bash
Claude Code 在 Windows 上需要 Git Bash 才能运行。请先下载安装 Git for Windows:
步骤 1:安装 Claude Code
# 安装稳定版本
irm https://claude.ai/install.ps1 | iex
# 安装最新版本
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest
# 安装指定版本
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
步骤 2:配置环境变量 PATH
安装完成后,需要将 Claude Code 添加到系统 PATH 中:
# 永久添加到用户 PATH 并立即生效
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Users\Administrator\.local\bin", "User")
$env:Path += ";C:\Users\Administrator\.local\bin"
💡 提示:如果你的用户名不是 Administrator,请将路径中的 Administrator 替换为你的实际用户名。
步骤 3:配置 API 环境变量
配置中转 API 的 Base URL 和 API Key:
# 设置 API Base URL
$env:ANTHROPIC_BASE_URL="https://api.claudecode.net.cn/api/claudecode"
# 设置 API Key
$env:ANTHROPIC_API_KEY="sk-ant-api03-pbKM2cfaKU******"
# 设置 Auth Token(与 API Key 相同)
$env:ANTHROPIC_AUTH_TOKEN="sk-ant-api03-pbKM2cfaKU******"
# 永久设置到用户环境变量
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.claudecode.net.cn/api/claudecode", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-pbKM2cfaKU******", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-ant-api03-pbKM2cfaKU******", "User")
📝 或者使用配置文件:在 ~/.claude/settings.json 中添加:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.claudecode.net.cn/api/claudecode",
"ANTHROPIC_API_KEY": "sk-ant-api03-pbKM2cfaKU******",
"ANTHROPIC_AUTH_TOKEN": "sk-ant-api03-pbKM2cfaKU******"
}
}
步骤 4:验证安装
# 查看版本
claude --version
# 查看帮助
claude --help
# 测试运行
claude "Hello, Claude!"
⚠️ 前置要求:安装 Git Bash
Claude Code 在 Windows 上需要 Git Bash 才能运行。请先下载安装: https://git-scm.com/downloads/win
步骤 1:安装 Claude Code
REM 安装稳定版本
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
REM 安装最新版本
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd latest && del install.cmd
REM 安装指定版本
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd
步骤 2:配置环境变量 PATH
安装完成后,需要手动添加到系统 PATH:
- 按
Win + R,输入sysdm.cpl,回车 - 点击"高级"标签 → "环境变量"
- 在"用户变量"中找到
Path,点击"编辑" - 点击"新建",添加:
C:\Users\Administrator\.local\bin - 点击"确定"保存,重启命令提示符
💡 提示:将路径中的 Administrator 替换为你的实际用户名。
步骤 3:配置 API 环境变量
同样在"环境变量"窗口中,点击"新建"添加以下三个变量:
| 变量名 | 变量值 |
|---|---|
ANTHROPIC_BASE_URL |
https://api.claudecode.net.cn/api/claudecode |
ANTHROPIC_API_KEY |
sk-ant-api03-pbKM2cfaKU****** |
ANTHROPIC_AUTH_TOKEN |
sk-ant-api03-pbKM2cfaKU****** |
📝 或者使用配置文件:创建文件 %USERPROFILE%\.claude\settings.json,内容如下:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.claudecode.net.cn/api/claudecode",
"ANTHROPIC_API_KEY": "sk-ant-api03-pbKM2cfaKU******",
"ANTHROPIC_AUTH_TOKEN": "sk-ant-api03-pbKM2cfaKU******"
}
}
步骤 4:验证安装
REM 查看版本
claude --version
REM 查看帮助
claude --help
REM 测试运行
claude "Hello, Claude!"
从 Node.js 版本迁移
一条命令完成迁移,保留所有配置和设置
自动迁移
如果你之前通过 npm 安装了 Claude Code,迁移到原生安装非常简单。运行以下命令会自动检测当前安装,并将其迁移到原生二进制版本:
claude install
迁移会保留的内容
API Keys
所有已配置的 API 密钥将被保留
自定义配置
settings.json 中的所有配置项
Subagents 定义
自定义的子代理配置
Slash Commands
自定义的斜杠命令
原生安装 vs Node.js 安装
为什么要切换到原生安装?
| 特性 | 原生安装 | Node.js 安装 |
|---|---|---|
| 依赖要求 | ✅ 无需任何依赖 | ❌ 需要 Node.js 18+ 和 npm |
| 安装复杂度 | ✅ 一条命令完成 | ⚠️ 需要先安装 Node.js |
| 启动速度 | ✅ 快 4 倍(JavaScriptCore) | ⚠️ 较慢(V8 引擎) |
| 版本兼容性 | ✅ 无版本冲突 | ❌ 可能有 Node.js 版本问题 |
| 自动更新 | ✅ 稳定可靠 | ⚠️ 偶尔出现问题 |
| 权限问题 | ✅ 无权限问题 | ❌ 可能需要 sudo(不推荐) |
| 文件大小 | ⚠️ 较大(包含运行时) | ✅ 较小(依赖外部 Node.js) |
| 平台支持 | ✅ macOS、Linux、Windows | ✅ macOS、Linux、Windows |
自动更新机制
保持 Claude Code 始终处于最新状态
自动检查
启动时和运行期间定期检查新版本
后台下载
在后台自动下载和安装更新
更新通知
安装完成后会显示通知
重启生效
下次启动时自动应用更新
手动更新
# 手动触发更新检查
claude update
禁用自动更新
如果你想完全控制更新时机,可以禁用自动更新:
# 在 shell 配置文件中添加(如 ~/.bashrc 或 ~/.zshrc)
export DISABLE_AUTOUPDATER=1
# 或在 settings.json 中配置
{
"DISABLE_AUTOUPDATER": "1"
}
常见问题
❓ 原生安装是如何工作的?
使用 Bun 的 --compile 功能将 TypeScript 代码、所有依赖和 Bun 运行时打包成单一的原生可执行文件。类似于 Go 或 Rust 编译出来的二进制文件。
❓ 为什么启动速度更快?
Bun 使用 Apple 的 JavaScriptCore 引擎(Safari 的 JS 引擎),优先优化启动时间和内存占用。而 Node.js 使用 V8 引擎,更注重长时间运行的性能。
❓ 需要卸载 Node.js 吗?
不需要。原生安装的 Claude Code 完全独立运行,不会影响系统中的 Node.js。你可以继续使用 Node.js 进行其他开发工作。
❓ Alpine Linux 支持吗?
支持,但需要先安装 libgcc、libstdc++ 和 ripgrep:apk add libgcc libstdc++ ripgrep,并设置 USE_BUILTIN_RIPGREP=0。
❓ 如何验证安装类型?
运行 claude doctor 命令可以检查你的安装类型、版本和系统配置。
❓ 可以回退到 npm 版本吗?
可以,但不推荐。你可以卸载原生版本后重新使用 npm install -g @anthropic-ai/claude-code 安装。
❓ Windows 安装后提示找不到 claude 命令?
需要将 C:\Users\你的用户名\.local\bin 添加到系统 PATH 环境变量中。可以使用 PowerShell 命令一键配置,或通过"系统属性 → 环境变量"手动添加。
❓ Windows 上需要 Git Bash 吗?
是的,Claude Code 在 Windows 上依赖 Git Bash 运行。请先从官网下载安装 Git for Windows:https://git-scm.com/downloads/win
❓ 如何配置中转 API?
设置三个环境变量:ANTHROPIC_BASE_URL(中转地址)、ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN(API 密钥)。也可以在 ~/.claude/settings.json 中配置。
开始使用 Claude Code
安装完成后,立即开始你的 AI 编程之旅
基本使用
# 进入你的项目目录
cd your-awesome-project
# 启动 Claude Code
claude
# 或直接提问
claude "帮我创建一个 React 组件"
认证选项
Claude Code 提供多种认证方式:
- Claude Console(默认):通过 console.anthropic.com 进行 OAuth 认证
- Claude App(Pro/Max 订阅):使用 Claude.ai 账户登录
- 企业平台:配置 Amazon Bedrock 或 Google Vertex AI
常用命令
# 查看版本
claude --version
# 系统诊断
claude doctor
# 手动更新
claude update
# 查看帮助
claude --help