Claude Code 原生安装完全指南

什么是原生安装？

Claude Code 原生安装是使用 Bun 编译器将整个应用打包成单一可执行文件的全新安装方式。它彻底摆脱了对 Node.js 运行时的依赖，提供了更快、更轻量的使用体验。

核心优势

无需 Node.js：不再需要安装 Node.js 和 npm，降低了入门门槛，避免了版本兼容问题
单一可执行文件：使用 Bun 编译成自包含的原生二进制文件，包含完整运行时，无需任何外部依赖
极速启动：启动时间从 2-3 秒缩短至 0.5-0.7 秒，提升 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
                

系统要求

支持的操作系统

Windows：Windows 10 1903 或更高版本（x64 架构）
macOS：macOS 11.0 (Big Sur) 或更高版本（Intel 或 Apple Silicon）
Linux：支持 glibc 2.17+ 的主流发行版（x64 架构）
- Ubuntu 18.04+ / Debian 10+
- CentOS 7+ / RHEL 7+
- Fedora 30+
- Arch Linux

最低硬件要求

内存：至少 2GB RAM（推荐 4GB+）
存储：100MB 可用磁盘空间
网络：互联网连接（用于 API 调用和自动更新）

安装指南

选择适合你的操作系统的安装方式

方法一：官方安装脚本（推荐）

适用于所有平台，自动检测系统并下载对应版本

Windows (PowerShell)

irm https://claude.ai/install.ps1 | iex

⚠️ 注意：Windows 需要先安装 Git Bash

macOS / Linux (Bash)

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

提示：安装脚本会自动：

检测你的操作系统和架构
下载最新版本的原生二进制文件
安装到用户目录（~/.local/bin）
配置 PATH 环境变量

方法二：Windows 详细安装步骤

步骤 1：安装 Git Bash（前置要求）

Claude Code 在 Windows 上需要 Git Bash 才能运行。请先下载安装：

下载地址：https://git-scm.com/downloads/win

步骤 2：使用 CMD 安装

                    curl -fsSL https://claude.ai/install.cmd -o install.cmd
install.cmd
                

步骤 3：配置环境变量 PATH

安装完成后，需要手动添加到系统 PATH：

按 Win + R，输入 sysdm.cpl，回车
点击"高级"标签，然后点击"环境变量"
在"用户变量"中，找到 Path，点击"编辑"
点击"新建"，添加：C:\Users\你的用户名\.local\bin
确定保存，重启 CMD 或 Git Bash

步骤 4：配置 API 环境变量

在"环境变量"窗口中，点击"新建"添加以下三个变量：

变量名	值
ANTHROPIC_BASE_URL	https://api.claudecode.net.cn/api/claudecode
ANTHROPIC_API_KEY	sk-ant-api03-你的密钥
ANTHROPIC_AUTH_TOKEN	sk-ant-api03-你的密钥

或者使用配置文件：创建文件 %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******"
  }
}
                    

从 Node.js 版本迁移

一条命令完成迁移，保留所有配置和设置

自动迁移

如果你之前通过 npm 安装了 Claude Code，迁移到原生安装非常简单。运行以下命令会自动检测当前安装，并将其迁移到原生二进制版本：

                    # 自动迁移命令
claude --migrate-to-native
                

迁移会保留的内容

API Keys：所有已配置的 API 密钥将被保留
自定义配置：settings.json 中的所有配置项
Subagents 定义：自定义的子代理配置
Slash Commands：自定义的斜杠命令

方法三：手动下载安装

适用于需要特定版本或离线安装的场景

1. 访问官方下载页面

打开浏览器访问：https://claude.ai/download

2. 选择对应平台下载

Windows：claude-windows-x64.exe
macOS：
- Intel Mac：claude-macos-x64.tar.gz
- Apple Silicon：claude-macos-arm64.tar.gz
- Universal：claude-macos-universal.tar.gz
Linux：claude-linux-x64.tar.gz

3. Windows 安装步骤

                    # 下载完成后
./claude-windows-x64.exe
                

按照安装向导完成安装，默认会添加到 PATH

4. macOS 安装步骤

                    # 解压文件
tar -xzf claude-macos-*.tar.gz

# 移动到系统路径
sudo mv claude /usr/local/bin/

# 添加执行权限
chmod +x /usr/local/bin/claude
                

5. Linux 安装步骤

                    # 解压文件
tar -xzf claude-linux-x64.tar.gz

# 移动到系统路径
sudo mv claude /usr/local/bin/

# 添加执行权限
chmod +x /usr/local/bin/claude
                

方法三：包管理器安装

macOS (Homebrew)

                    # 安装
brew install claude-code

# 更新
brew upgrade claude-code
                

Windows (Scoop)

                    # 添加 bucket
scoop bucket add claude

# 安装
scoop install claude-code
                

Linux (APT)

                    # 添加 GPG 密钥
curl -fsSL https://claude.ai/gpg.key | sudo apt-key add -

# 添加仓库
echo "deb https://claude.ai/apt stable main" | sudo tee /etc/apt/sources.list.d/claude.list

# 安装
sudo apt update
sudo apt install claude-code
                

配置说明

验证安装

                    # 检查版本
claude --version

# 查看帮助
claude --help

# 运行系统诊断
claude doctor
                

API 配置

原生版本与 npm 版本使用相同的 API 配置方式

方式一：环境变量（推荐）

                    # Windows (PowerShell)
$env:ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"
$env:ANTHROPIC_AUTH_TOKEN="sk-ant-api03-你的密钥"

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"
export ANTHROPIC_AUTH_TOKEN="sk-ant-api03-你的密钥"
                

方式二：配置文件

创建配置文件 ~/.claude/config.json：

                    {
  "apiKey": "sk-ant-api03-你的密钥",
  "authToken": "sk-ant-api03-你的密钥",
  "baseUrl": "https://api.anthropic.com",
  "model": "claude-3-sonnet-20241022"
}
                

配置文件详解

配置项	说明	默认值
apiKey	Anthropic API 密钥	必填
authToken	认证令牌	同 apiKey
baseUrl	API 服务器地址	https://api.anthropic.com
model	默认模型	claude-3-sonnet-20241022
maxTokens	最大输出 token 数	4096
temperature	生成温度（0-1）	0.7

使用指南

基本命令

                    # 启动交互式会话
claude

# 直接提问
claude "写一个 Python Hello World 程序"

# 查看版本
claude --version

# 系统诊断
claude doctor

# 更新到最新版本
claude update

# 查看配置
claude config show

# 重置配置
claude config reset
                

高级功能

项目初始化

                    # 在当前目录初始化 Claude 项目
claude init

# 指定项目类型
claude init --type react

# 使用自定义模板
claude init --template ./my-template
                

文件操作

                    # 查看文件
claude show src/App.js

# 编辑文件
claude edit src/App.js "添加错误边界"

# 创建新文件
claude create utils/api.js "实现 API 调用函数"
                

Git 集成

                    # 生成提交信息
claude commit

# 代码审查
claude review

# 生成 PR 描述
claude pr
                

原生版本 vs npm 版本对比

特性	原生版本	npm 版本	说明
安装方式	单文件	npm 包	原生版本更简单
依赖要求	无	Node.js 18+	原生版本零依赖
启动时间	0.5-0.7秒	2-3秒	原生版本快 4 倍
内存占用	30-50MB	80-120MB	原生版本节省 60%
更新方式	自动更新	npm update	都支持自动更新
功能完整性	100%	100%	功能完全一致
适用场景	生产环境	开发环境	根据需求选择

建议：

开发环境：可以使用 npm 版本，方便与其他 Node.js 工具集成
生产环境：推荐原生版本，更轻量、启动更快
CI/CD：强烈推荐原生版本，减少构建时间和资源占用

常见问题

Q1: 原生安装是如何工作的？

回答：使用 Bun 的 --compile 功能将 TypeScript 代码、所有依赖和 Bun 运行时打包成单一的原生可执行文件。类似于 Go 或 Rust 编译出来的二进制文件。

Q2: 为什么启动速度更快？

回答：Bun 使用 Apple 的 JavaScriptCore 引擎（Safari 的 JS 引擎），优先优化启动时间和内存占用。而 Node.js 使用 V8 引擎，更注重长时间运行的性能。

Q3: 需要卸载 Node.js 吗？

回答：不需要。原生安装的 Claude Code 完全独立运行，不会影响系统中的 Node.js。你可以继续使用 Node.js 进行其他开发工作。

Q4: Alpine Linux 支持吗？

回答：Alpine Linux 使用 musl libc，而原生版本基于 glibc，因此不支持。建议使用 Ubuntu、Debian、CentOS 等主流发行版。

Q5: 如何验证安装类型？

回答：运行 claude doctor 命令可以检查你的安装类型、版本和系统配置。

Q6: 可以回退到 npm 版本吗？

回答：可以，但不推荐。你可以卸载原生版本后重新使用 npm install -g @anthropic-ai/claude-code 安装。

Q7: Windows 安装后提示找不到 claude 命令？

解决：需要将 C:\Users\你的用户名\.local\bin 添加到系统 PATH 环境变量中。可以使用 PowerShell 命令一键配置，或通过"系统属性 → 环境变量"手动添加。

Q8: Windows 上需要 Git Bash 吗？

回答：是的。原生版本在 Windows 上通过 Git Bash 运行，因为提供了更好的 Unix 兼容性。安装 Git for Windows 后会自动包含 Git Bash。

Q9: 如何配置中转 API？

回答：设置三个环境变量：ANTHROPIC_BASE_URL（中转地址）、ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN（API 密钥）。也可以在 ~/.claude/settings.json 中配置。

Q10: Windows 显示安全警告

问题：运行 .exe 文件时 Windows Defender 提示安全风险

解决：

点击"更多信息"
选择"仍要运行"
或将文件添加到 Windows Defender 白名单

Q11: Linux/macOS 权限被拒绝

问题：执行 claude 命令时提示 permission denied

解决：

chmod +x /usr/local/bin/claude

Q12: 自动更新失败

问题：claude update 命令执行失败

解决：

手动下载最新版本替换旧文件
检查网络连接和防火墙设置
使用管理员权限运行

高级配置

环境变量完整列表

                    # API 配置
ANTHROPIC_API_KEY=你的API密钥
ANTHROPIC_AUTH_TOKEN=你的认证令牌
ANTHROPIC_BASE_URL=https://api.anthropic.com

# 行为配置
CLAUDE_MODEL=claude-3-sonnet-20241022
CLAUDE_MAX_TOKENS=4096
CLAUDE_TEMPERATURE=0.7

# 禁用自动更新
DISABLE_AUTOUPDATER=1

# 设置配置文件路径
CLAUDE_CONFIG_PATH=/custom/path/config.json
                

CI/CD 集成

GitHub Actions 示例

                    name: Claude Code Example
on: [push]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | sh
      - name: Run Claude
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: claude "review this PR" --output pr-review.md
                

性能优化建议

使用 SSD：虽然不是必须，但 SSD 可以进一步提升启动速度
配置代理：如果网络环境受限，配置 HTTP 代理：
export HTTP_PROXY=http://proxy.example.com:8080 export HTTPS_PROXY=http://proxy.example.com:8080
缓存管理：Claude 会自动缓存常用数据，清理缓存：
claude cache clear

卸载指南

Windows

                    # 方法一：使用卸载程序
# 在"应用和功能"中找到 Claude Code 并卸载

# 方法二：手动删除
Remove-Item "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item "$env:USERPROFILE\.claude" -Recurse -Force
                

macOS

                    # 删除主程序
sudo rm -f /usr/local/bin/claude

# 删除配置文件
rm -rf ~/.claude

# 如果使用 Homebrew 安装
brew uninstall claude-code
                

Linux

                    # 删除主程序
sudo rm -f /usr/local/bin/claude

# 删除配置文件
rm -rf ~/.claude

# 如果使用 APT 安装
sudo apt remove claude-code
                

总结

Claude Code 原生版本通过 Bun 编译技术实现了零依赖、极速启动的全新体验。它不仅保留了所有原有功能，还大幅提升了性能和便携性。无论是个人开发、企业部署还是 CI/CD 集成，原生版本都是更优的选择。

快速开始命令

                    # 一键安装
curl -fsSL https://claude.ai/install.sh | sh

# 配置 API
export ANTHROPIC_API_KEY="你的密钥"

# 开始使用
claude
                

下一步：

查看官方文档了解更多功能
探索 GitHub 仓库参与开源贡献
加入社区交流获取最佳实践