# Claude Code全平台安装与首项目实战 > 本教程面向零基础开发者，系统讲解 Claude Code 的运行原理、全平台（macOS/Linux/Windows）安装路径选择、三种认证方式对比决策、项目级配置（`CLAUDE.md` 与 `settings.json`），并通过一个完整的可运行 CLI 待办工具项目串起从安装到首次运行的完整链路，附带新手高频报错避坑手册。适合从未接触过 AI 终端工具、希望从图形化 AI 助手迁移到命令行工作流的学习者。 --- ## 一、概述 Claude Code 是 Anthropic 官方推出的**终端原生（terminal-native）AI 编程助手**。与 ChatGPT 网页版、Cursor 图形 IDE 不同，它直接运行在你的命令行里，能够读写本地文件、执行 Shell 命令、运行测试、操作 Git，相当于一个理解你整个代码库的「智能同事」坐镇终端。 **适用人群**： - 从未用过 AI 编程工具、想从零搭起一个真实项目的开发者 - 习惯了网页版 AI 对话、希望让 AI 直接动手改代码的进阶用户 - 需要在团队中标准化 AI 协作流程的工程负责人 **学习目标**：读完本文，你能独立在任意操作系统装好 Claude Code、完成认证、配置好首个项目，并跑通一个可运行的 CLI 应用，同时掌握排错能力。 --- ## 二、前置条件 在动手安装之前，请确认你的环境满足以下要求： | 条件 | 说明 | 检查命令 | |------|------|----------| | 终端 | macOS Terminal / iTerm2、Linux 终端、Windows Terminal（推荐 WSL2） | — | | 联网环境 | 需访问 `claude.ai` 与 `api.anthropic.com` | `curl -I https://claude.ai` | | Node.js（仅 npm 安装方式） | ≥ 18，建议 LTS 版 | `node -v` | | Git | 任意现代版本 | `git --version` | | 一个账号 | Claude 订阅账号 **或** Anthropic Console API 账号 | — | **关键提醒**：Windows 用户**强烈建议使用 WSL2（Ubuntu）**而非原生 PowerShell。虽然 Claude Code 在 Windows 原生终端下也能运行，但大量构建工具、Shell 脚本、Git 钩子在 WSL 下兼容性远优于原生环境，可避免后续 80% 的「环境问题」。 --- ## 三、理解安装方式：先做一道选择题 很多人卡在第一步，就是因为没搞清 Claude Code 到底有几种安装方式、彼此有何区别。这里先讲清楚决策逻辑，再给命令。 ### 3.1 两种安装路径 Claude Code 目前提供两条主流安装路径： 1. **Native Installer（原生安装器）** —— 官方独立二进制，无需 Node.js 2. **npm 全局安装** —— 通过 `npm install -g` 安装 Node 包 ### 3.2 决策矩阵 | 维度 | Native Installer | npm 安装 | |------|------------------|----------| | 是否需要 Node.js | ❌ 不需要 | ✅ 需要 ≥ 18 | | 安装速度 | 快（单脚本） | 取决于 npm 源 | | 升级方式 | `claude update` 自更新 | `npm update -g` | | 跨平台一致性 | 高 | 依赖本地 Node 环境 | | 适合人群 | 新手、无 Node 经验者 | 已有 Node 工具链的开发者 | **结论**：如果你是零基础、电脑里没有装 Node.js，**直接选 Native Installer**；如果你是前端/全栈开发者、已经有完整的 Node 环境，npm 安装更贴合既有习惯。 --- ## 四、各平台安装实操 ### 步骤 1：选择并执行安装命令 #### 方案 A：Native Installer（推荐新手） ```bash # macOS / Linux（含 WSL2） curl -fsSL https://claude.ai/install.sh | bash ``` ```powershell # Windows PowerShell（原生） irm https://claude.ai/install.ps1 | iex ``` **预期结果**：脚本会下载二进制文件并安装到用户目录（通常是 `~/.local/bin` 或类似路径），随后自动提示你将路径加入 `PATH`。安装完成后执行： ```bash claude --version ``` 若输出形如 `Claude Code v1.x.x`，说明安装成功。 #### 方案 B：npm 全局安装 ```bash npm install -g @anthropic-ai/claude-code ``` **预期结果**：npm 会拉取官方包并链接到全局 bin 目录。完成后执行 `claude --version` 验证。 #### 方案 C：通过 Homebrew（macOS/Linux 可选） 部分版本支持 Homebrew Cask 安装，适合习惯用包管理器的用户： ```bash brew install --cask claude-code ``` ### 步骤 2：验证 PATH 与可执行性 安装后如果 `claude` 命令「未找到」，通常是 `PATH` 未生效： ```bash # macOS / Linux：检查可执行位置 which claude # 临时加入 PATH（以 zsh 为例） echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` Windows 原生安装会把可执行路径写入用户级 PATH，重启 Terminal 即可生效。 --- ## 五、认证：三种方式的对比与选择 安装完成后，第一次运行 `claude` 时会要求认证。这里是最容易让新手困惑的地方——究竟用什么登录？答案是：取决于你的账号类型。 ### 5.1 三种认证方式 | 认证方式 | 来源 | 计费 | 适合人群 | |----------|------|------|----------| | **Claude 订阅登录** | Claude Pro / Max 订阅 | 包含在订阅内（有用量上限） | 个人开发者，不想单独管 API 账单 | | **Console API Key** | Anthropic Console 控制台 | 按 Token 用量付费 | 团队、需要精确控成本者 | | **第三方/自建网关** | Bedrock、Vertex AI 等 | 走云厂商账单 | 企业合规、私有化部署 | ### 5.2 决策建议 - **个人学习/副业项目** → 用 Claude 订阅登录，零额外配置 - **公司项目/需要团队共享** → 用 Console API Key，便于账单与配额管理 - **合规要求严格的金融/政企** → 走 Bedrock / Vertex AI 网关 ### 5.3 实操认证 #### 方式一：订阅账号登录（默认） ```bash claude ``` 首次运行会提示你打开浏览器完成 OAuth 授权，授权后终端自动获得凭证。整个过程无需手动复制 Token。 #### 方式二：使用 API Key ```bash # 设置环境变量（推荐写入 shell 配置文件持久化） export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx" ``` ```bash claude ``` Claude Code 会自动识别环境变量中的 Key 并采用 Console 计费。 #### 方式三：指定自定义网关（企业） ```bash export ANTHROPIC_BASE_URL="https://your-gateway.example.com" export ANTHROPIC_API_KEY="your-key" claude ``` **预期结果**：认证成功后，终端会进入交互式会话界面，底部显示当前模型与上下文状态。 --- ## 六、首次交互：认识 REPL 启动 `claude` 后进入的就是交互式 REPL（Read-Eval-Print Loop）。它和网页对话框最大的区别是——它能动手。 ```bash $ claude > 帮我看看当前目录有什么文件 ``` Claude 会调用内置的文件浏览工具，列出目录树，并给出解读。常用快捷操作： - `/help` —— 查看所有内置斜杠命令 - `/model` —— 切换模型（Sonnet / Opus / Haiku） - `/clear` —— 清空当前会话上下文 - `/config` —— 打开配置面板 - `Esc Esc` —— 回溯编辑上一条消息 - `Ctrl+C` —— 中断当前操作 **新手提示**：第一次不必急着改代码，先用自然语言让它「描述一下这个项目」，观察它如何调用工具，建立对工作流的直觉。 --- ## 七、项目配置：让 AI 真正懂你的项目 裸用 Claude Code 已经能干活，但要做到「团队标准化、AI 行为可预测」，必须配置两个核心文件。 ### 7.1 `CLAUDE.md` —— 项目记忆 在项目根目录创建 `CLAUDE.md`，把项目的约定、技术栈、命名规范写进去。Claude Code 每次启动会自动读取它作为上下文。 ```markdown # 项目说明：todo-cli ## 技术栈 - 语言：Node.js 20+，纯 ESM - 测试：Vitest - Lint：ESLint + Prettier ## 命名约定 - 函数：camelCase - 文件：kebab-case - 常量：UPPER_SNAKE_CASE ## 开发命令 - 安装依赖：`npm install` - 运行：`npm run dev` - 测试：`npm test` ``` **作用**：避免每次都要重复交代背景，AI 会自觉遵循你的规范。 ### 7.2 `settings.json` —— 权限与行为 位于 `.claude/settings.json`，控制工具权限、环境变量、钩子等。新手最该配的是**权限白名单**，减少反复确认： ```json { "permissions": { "allow": [ "Bash(npm install)", "Bash(npm test)", "Bash(npm run dev)", "Read(**)", "Edit(src/**)" ] }, "env": { "NODE_ENV": "development" } } ``` **含义**：读取任意文件、编辑 `src/` 下文件、运行这三条 npm 命令时自动放行，无需每次手动确认 `y/n`。其余操作仍会弹确认，保证安全。 --- ## 八、第一个项目：todo-cli 完整实战 下面用 Claude Code 从零搭建一个可运行的命令行待办工具，串起整个流程。 ### 8.1 初始化项目 ```bash mkdir todo-cli && cd todo-cli git init npm init -y ``` ### 8.2 创建 `CLAUDE.md` 写入第七节的示例内容。然后启动 Claude Code： ```bash claude ``` ### 8.3 用自然语言下达需求 在 REPL 中输入： ``` 用 Node.js + commander 实现一个 CLI 待办工具，要求： 1. add <内容> 添加任务 2. list 列出所有任务（带序号和完成状态） 3. done <序号> 标记完成 4. 数据用 JSON 持久化到 ~/.todo-cli.json 帮我搭建完整代码，并在 package.json 里配置 bin 和 start 命令。 ``` ### 8.4 预期产出 Claude 会自动安装依赖、生成 `src/index.js`、更新 `package.json`。核心代码大致如下： ```javascript import { program } from 'commander'; import { readFile, writeFile } from 'node:fs/promises'; import { homedir } from 'node:os'; import { join } from 'node:path'; const DB = join(homedir(), '.todo-cli.json'); async function load() { try { const raw = await readFile(DB, 'utf-8'); return JSON.parse(raw); } catch { return []; } } async function save(todos) { await writeFile(DB, JSON.stringify(todos, null, 2)); } program .command('add ') .description('添加任务') .action(async (text) => { const todos = await load(); todos.push({ text, done: false }); await save(todos); console.log(`✅ 已添加：${text}`); }); program .command('list') .description('列出任务') .action(async () => { const todos = await load(); if (todos.length === 0) return console.log('（暂无任务）'); todos.forEach((t, i) => { console.log(`${t.done ? '[x]' : '[ ]'} ${i + 1}. ${t.text}`); }); }); program .command('done ') .description('标记完成') .action(async (index) => { const todos = await load(); const i = Number(index) - 1; if (!todos[i]) return console.log('❌ 序号无效'); todos[i].done = true; await save(todos); console.log(`🎉 已完成：${todos[i].text}`); }); program.parse(); ``` `package.json` 关键字段： ```json { "type": "module", "bin": { "todo": "src/index.js" }, "scripts": { "start": "node src/index.js" }, "dependencies": { "commander": "^12.0.0" } } ``` ### 8.5 运行验证 ```bash node src/index.js add "学习 Claude Code" node src/index.js add "写第一个项目" node src/index.js list node src/index.js done 1 node src/index.js list ``` **预期输出**： ``` ✅ 已添加：学习 Claude Code ✅ 已添加：写第一个项目 [ ] 1. 学习 Claude Code [ ] 2. 写第一个项目 🎉 已完成：学习 Claude Code [x] 1. 学习 Claude Code [ ] 2. 写第一个项目 ``` ### 8.6 让 Claude 处理 Git 提交 ``` 帮我创建 .gitignore（忽略 node_modules），然后提交所有文件，commit message 用中文概括本次初始化。 ``` Claude 会自动生成 `.gitignore`、暂存、提交。**注意**：根据团队规范，提交前请人工核对 diff。 --- ## 九、新手高频报错避坑手册 | 报错/现象 | 原因 | 解决方案 | |-----------|------|----------| | `command not found: claude` | PATH 未生效 | 重启终端；或 `source ~/.zshrc` | | `EACCES: permission denied` | npm 全局目录无权限 | 用 nvm 管理 Node，或 `sudo chown` 修复 | | 认证后立即报 401 | Token 过期/错误 | 重新 `claude` 触发登录，或检查 `ANTHROPIC_API_KEY` | | Windows 上 Git/脚本异常 | 原生 PowerShell 兼容差 | 切换到 WSL2 Ubuntu | | 中文乱码 | 终端编码非 UTF-8 | 设置 `LANG=zh_CN.UTF-8` 或换用 Windows Terminal | | 卡在「thinking」不动 | 网络/区域限制 | 配置代理：`export HTTPS_PROXY=...` | | 工具调用被反复拦截 | 未配置权限白名单 | 编辑 `.claude/settings.json` 的 `permissions.allow` | | `npm install` 极慢 | npm 源在国外 | `npm config set registry https://registry.npmmirror.com` | --- ## 十、整体工作流程图 ```mermaid flowchart TD A[确认环境: 终端/联网/账号] --> B{有无 Node.js?} B -- 否 --> C[Native Installer 安装] B -- 是 --> D[npm 全局安装] C --> E[验证 claude --version] D --> E E --> F{账号类型?} F -- 个人订阅 --> G[OAuth 浏览器登录] F -- Console --> H[设置 ANTHROPIC_API_KEY] F -- 企业 --> I[配置自定义网关] G --> J[进入 REPL] H --> J I --> J J --> K[创建项目目录] K --> L[编写 CLAUDE.md] L --> M[配置 settings.json 权限] M --> N[自然语言下达需求] N --> O[Claude 调用工具: 读/写/执行] O --> P[运行测试验证] P --> Q[Git 提交] Q --> R[首个项目完成] ``` --- ## 十一、延伸阅读 - **Claude Code 官方文档首页** —— 最权威的功能与配置参考，建议收藏常查 - **Anthropic 官方 GitHub 仓库** —— Issue 区与示例项目，是排错第一现场 - **Claude Code 最佳实践（Anthropic 工程博客）** —— 官方总结的高效使用技巧 - **Anthropic Console 控制台** —— 管理 API Key、查看用量与账单 - **MCP（Model Context Protocol）官方站** —— 了解如何接入外部工具，为后续进阶铺路 --- ## 十二、训练营适用性评估 | 训练营类型 | 适用性 | 预计教学时长 | 备注 | |-----------|--------|-------------|------| | 编程零基础训练营 | ⭐⭐⭐⭐⭐ | 2.5 小时 | 作为「AI 时代开发环境搭建」第一课 | | 前端/全栈就业营 | ⭐⭐⭐⭐⭐ | 2 小时 | npm 路径贴合既有习惯，上手快 | | 企业内训/团队赋能 | ⭐⭐⭐⭐ | 3 小时 | 需补充 API Key 与权限治理章节 | | 算法/科研训练营 | ⭐⭐⭐ | 1.5 小时 | 重点讲 CLI 自动化与脚本集成 | | DevOps/SRE 训练营 | ⭐⭐⭐⭐ | 2 小时 | 强调 settings.json、钩子、CI 集成 | **教学节奏建议**：30 分钟讲解原理 → 60 分钟动手安装认证 → 90 分钟做 todo-cli 实战 → 15 分钟答疑避坑。**考核点**：学员能独立在指定平台完成安装、认证，并跑通一个可执行项目。 --- ## 参考来源 1. [Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code/overview) — Anthropic 官方出品，涵盖概览、安装、配置、命令参考的权威资料库 2. [Claude Code 安装与设置指南](https://docs.claude.com/en/docs/claude-code/setup) — 官方 Native Installer 与 npm 安装、认证方式的详细步骤说明 3. [Claude Code GitHub 官方仓库](https://github.com/anthropics/claude-code) — 官方维护的代码库与 Issue 区，是排错与跟进新特性的第一现场 4. [Anthropic 官方开发者控制台](https://console.anthropic.com/) — 管理 API Key、查看用量配额与账单的入口 5. [Claude Code 最佳实践（Anthropic 工程博客）](https://www.anthropic.com/engineering) — 官方工程团队总结的高效使用模式与上下文工程技巧 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。