什么是原生安装?

Claude Code 从基于 Node.js 的应用转变为单一的自包含可执行文件

无需 Node.js

不再需要安装 Node.js 和 npm,降低了入门门槛,避免了版本兼容问题。

🎯

单一可执行文件

使用 Bun 编译成自包含的原生二进制文件,包含完整运行时,无需任何外部依赖。

🚀

启动速度快 4 倍

基于 JavaScriptCore 引擎,优先优化启动时间和内存占用,特别适合 CLI 工具。

🔄

稳定的自动更新

改进的自动更新机制,后台下载安装,无需手动干预。

🌍

全平台支持

支持 macOS、Linux、Windows(WSL/Git Bash),一次编译,到处运行。

🛡️

更安全可靠

避免 npm 权限问题和安全风险,提供更稳定的运行环境。

技术实现:从 TypeScript 到原生二进制

使用 Bun 将 TypeScript 代码编译成单一可执行文件

编译过程

  1. 转译 TypeScript:将 TypeScript 代码转译成 JavaScript
  2. 字节码编译:使用 --bytecode 标志预编译成 JavaScriptCore 字节码
  3. 打包依赖:将所有 npm 包和代码打包进来
  4. 嵌入运行时:将完整的 Bun 运行时(基于 JavaScriptCore)一起打包
  5. 生成二进制:输出平台原生的自包含可执行文件
Bun 编译命令示例
# 使用 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 ❌ 不再需要(原生安装)

安装指南

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

一键安装(推荐)

macOS、Linux 和 WSL
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 安装

Homebrew Cask
brew install --cask claude-code

优势:可以通过 brew upgrade 统一管理所有应用的更新。

更新 Claude Code

Homebrew 更新
# 更新 Homebrew
brew update

# 升级 Claude Code
brew upgrade --cask claude-code

⚠️ 前置要求:安装 Git Bash

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

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

步骤 1:安装 Claude Code

Windows PowerShell
# 安装稳定版本
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(一键配置)
# 永久添加到用户 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 Code
# 查看版本
claude --version

# 查看帮助
claude --help

# 测试运行
claude "Hello, Claude!"

⚠️ 前置要求:安装 Git Bash

Claude Code 在 Windows 上需要 Git Bash 才能运行。请先下载安装: https://git-scm.com/downloads/win

步骤 1:安装 Claude Code

Windows 命令提示符
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:

  1. Win + R,输入 sysdm.cpl,回车
  2. 点击"高级"标签 → "环境变量"
  3. 在"用户变量"中找到 Path,点击"编辑"
  4. 点击"新建",添加:C:\Users\Administrator\.local\bin
  5. 点击"确定"保存,重启命令提示符

💡 提示:将路径中的 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:验证安装

测试 Claude Code
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_KEYANTHROPIC_AUTH_TOKEN(API 密钥)。也可以在 ~/.claude/settings.json 中配置。

开始使用 Claude Code

安装完成后,立即开始你的 AI 编程之旅

基本使用

启动 Claude Code
# 进入你的项目目录
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