Ubuntu 搭建 Claude Code 开发环境

环境搭建与配置全流程

你可以参考下面的流程图，对整个搭建和使用过程有一个整体的认识：

步骤 1：环境准备

在开始之前，请打开终端，确保你的系统满足以下条件：

安装 Git（可选但强烈推荐）： Claude Code 能更好地理解 Git 历史记录和进行版本控制操作。

sudo apt install -y git

安装 Node.js（推荐 18.19.0 或更高版本）： Claude Code 可以通过 npm 安装，所以 Node.js 是必需的。

# 使用 NodeSource 仓库安装 Node.js 20.x LTS 版本
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# 验证安装
node --version
npm --version

如果你计划使用其他安装方式（如原生安装），Node.js 不是必需的，但为了后续的通用性和工具链完整性，仍然推荐安装。

更新系统包：

sudo apt update && sudo apt upgrade -y

步骤 2：安装 Claude Code（二选一）

你可以根据个人喜好选择以下任一方式。

方式 A：通过 npm 全局安装（通用性最强）

这是最直接、最通用的方法，适用于大多数开发者。

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

⚠️ 重要提示：如果遇到权限错误（EACCES），切勿使用 sudo。请参考下文'故障排除'部分，配置 npm 使用用户级目录。

方式 B：通过官方脚本原生安装（无需 Node.js，自动更新）

如果你希望工具独立于 Node.js 环境并开启自动更新，可以选择此方法。

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

步骤 3：验证安装

无论使用哪种方式，安装成功后，运行以下命令检查版本：

claude --version

如果显示类似 2.x.x (Claude Code) 的版本号，则安装成功。你还可以运行诊断命令，确保所有组件正常工作：

claude doctor

步骤 4：认证与配置

首次启动 Claude Code 需要进行身份认证。

1. 完成 OAuth 认证：
   • 终端会显示一个验证码并自动打开浏览器。
   • 你需要登录你的 Anthropic Console 账号（确保账户内有 API 余额）或拥有 Claude Pro/Max 订阅的 claude.ai 账号。
   • 在网页上完成授权后，返回终端，认证即完成。

（可选）通过配置文件认证： 你也可以在 ~/.claude/settings.json 文件中直接配置 API Key。这种方式适合服务器或无图形界面的环境。

{"env":{"ANTHROPIC_AUTH_TOKEN":"你的-API-Key","ANTHROPIC_BASE_URL":"你的-API-代理地址（如果需要）"}}

启动 Claude Code：

claude

步骤 5：项目初始化——创建'灵魂文件'CLAUDE.md

认证成功后，进入你的项目目录，再次运行 claude。Claude Code 会询问是否创建 CLAUDE.md 文件，请务必选择'是'。

这个文件是 Claude Code 的长期记忆和操作手册。你可以在这个文件里写下项目的构建命令、测试命令、编码规范和架构说明。例如：

# 项目指南
## 常用命令
- 构建：npm run build
- 测试：npm test
## 编码规范
- 使用函数式组件
- 所有 API 请求放在 /src/api 目录

之后每次启动，Claude Code 都会自动加载这个文件，让它更懂你的项目。

步骤 6：开始使用

一切就绪后，你就可以在终端里与 Claude Code 对话了。

• 交互模式：直接输入 claude 进入对话，用自然语言描述你的需求，比如'帮我写一个 React Hook 用来获取数据'。
• 查看帮助：在交互模式中，输入 /help 可以查看所有内置命令。

一次性任务：使用 -p 参数快速执行一个任务。

claude -p "解释一下这个函数"

🔧 进阶使用与核心技巧

• 策划与执行分离：对于复杂任务，建议先在 Claude.ai 网页端或与其他模型进行深度沟通，生成详细的实施计划（如 Checklist），再交给 Claude Code 去精确执行。这能有效避免 Token 浪费和逻辑偏离。
• 关键命令速查：
  • /init：在项目中初始化或更新 CLAUDE.md。
  • /compact：当对话历史过长时，压缩上下文以节省 Token 费用。
  • /cost：查看当前会话的 Token 消耗。
  • /review：请求对当前代码更改进行审查。
  • Plan Mode：双击 Shift+Tab 进入规划模式，AI 会先制定计划，经你批准后再执行，是'谋定而后动'的关键。
  • ! 前缀：在提示符后直接执行 Bash 命令，例如 ! git status，无需退出 Claude Code。
  • @ 提及：快速将文件或目录加入上下文，例如 分析 @src/utils/helpers.js。

🚨 故障排除

• claude: command not found：可能是 PATH 未包含安装目录。如果是 npm 安装，运行 echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc 并执行 source ~/.bashrc。
• 认证失败：可以尝试运行 /logout 后重新执行 claude 进行授权，或删除 ~/.config/claude-code/auth.json 缓存文件后重试。

npm 安装权限错误 (EACCES)：永远不要使用 sudo。正确做法是配置 npm 使用用户目录：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# 之后重新运行 npm install -g ...