Claude Code 完整入门教程：从安装到完成第一次代码修改Claude Code 是 Anthropic 推出的智

更新时间：2026 年 9 月 27 日
适合人群：第一次使用 Claude Code 的开发者
阅读与实践时间：约 20～30 分钟
最终成果：完成安装、登录、项目分析、代码修改、测试验证和 Git 检查

Claude Code 是 Anthropic 推出的智能编程工具。它可以在终端或 IDE 中读取项目文件、解释代码、修改程序、执行测试，并协助处理 Git 工作流。

它与普通聊天机器人的主要区别是：Claude Code 不只是给出代码建议，还能在获得相应权限后直接操作当前项目。

本文将从安装开始，带你完成一次相对完整、安全且可验证的 Claude Code 开发流程。

一、使用前需要准备什么

当前版本支持以下系统环境：

macOS 13.0 或更高版本
Windows 10 1809、Windows Server 2019 或更高版本
Ubuntu 20.04、Debian 10、Alpine Linux 3.19 或更高版本
x64 或 ARM64 处理器
至少 4GB 内存
可用的互联网连接

Claude Code 需要 Claude Pro、Max、Team、Enterprise 或 Anthropic Console 账户；Claude 免费套餐目前不包含 Claude Code。

开始前建议准备一个已有的 Git 项目。没有项目也没关系，可以先创建一个测试目录：

mkdir claude-code-demo
cd claude-code-demo
git init

官方说明：Claude Code 系统要求与账户说明

二、安装 Claude Code

1. 原生安装：官方推荐

macOS、Linux 或 WSL：

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

Windows PowerShell：

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

Windows CMD：

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

安装完成后，关闭并重新打开终端，然后检查版本：

claude --version

正常情况下会输出类似：

2.x.x (Claude Code)

还可以执行只读诊断：

claude doctor

它会检查安装状态、配置文件和更新情况，不会启动编程会话。原生版本默认自动更新。

2. 使用 Homebrew 安装

macOS 用户也可以执行：

brew install --cask claude-code

Homebrew 中的 claude-code 通常跟踪相对稳定的发布通道，但不会由 Claude Code 自动更新。后续可以手动升级：

brew upgrade claude-code

3. 使用 WinGet 安装

winget install Anthropic.ClaudeCode

更新命令：

winget upgrade Anthropic.ClaudeCode

4. 使用 npm 安装

如果已经安装 Node.js，也可以使用：

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

当前 npm 包要求 Node.js 22 或更高版本。不要在命令前添加 sudo，否则可能产生权限和安全问题。

官方文档：Claude Code 安装指南

三、登录 Claude Code

进入项目目录：

cd /path/to/your-project

启动 Claude Code：

claude

首次运行时会要求登录。按照终端提示，在浏览器中完成认证即可。

支持的主要认证方式包括：

Claude Pro、Max、Team 或 Enterprise 订阅
Anthropic Console 按量计费账户
Amazon Bedrock
Google Cloud
Microsoft Foundry

以后需要切换账户时，可在 Claude Code 会话内输入：

/login

也可以在普通终端中查看登录状态：

claude auth status --text

退出登录：

claude auth logout

需要特别注意：如果系统中存在 ANTHROPIC_API_KEY 环境变量，Claude Code 可能使用该 API Key，并产生单独的 API 用量费用，而不是消耗 Claude 订阅额度。

中国大陆用户的接入建议

截至本文更新时间，中国大陆未列入 Anthropic 公布的 Claude.ai 和商业 API 支持地区。因此，不建议在中国大陆注册、登录或直接使用 Claude 官方订阅账号。Anthropic 明确要求用户位于支持地区，并会使用 IP 地址等信号判断大致位置；从不支持地区创建账号也可能触发账号限制。

不建议通过 VPN、代理或伪造位置绕过官方地区限制。如果你本人合法位于支持地区，应遵守当地法律和 Anthropic 的服务条款，使用本人账号，不共享登录凭证，并保持正常、稳定的网络环境。

四、认识 Claude Code 的工作方式

启动 Claude Code 后，可以直接用自然语言下达任务：

请介绍这个项目的用途、技术栈、目录结构和启动方式，暂时不要修改文件。

Claude Code 会按需读取当前项目中的文件，因此通常不需要逐个上传源代码。

第一次接触一个项目时，建议先让它理解代码，而不是立刻要求修改：

请分析这个项目：

1. 说明主要技术栈
2. 找出应用入口
3. 解释核心模块之间的关系
4. 列出构建、测试和代码检查命令
5. 暂时不要修改任何文件

随后可以逐步深入：

用户登录请求从前端到数据库经过了哪些文件？

这个项目的异常处理机制是什么？

找出与订单计费有关的代码，并说明完整调用链。

“先理解、再计划、后修改”通常比直接输入“帮我优化项目”更可靠。

五、使用 Plan mode 制定方案

对于影响多个文件或自己不熟悉的代码，建议先进入 Plan mode：

claude --permission-mode plan

Plan mode 下，Claude 可以读取和分析代码，但不会直接修改文件。你可以先要求：

分析登录接口偶尔返回 500 的原因。

请先完成以下工作：

1. 找到相关调用链
2. 确定根本原因
3. 列出需要修改的文件
4. 给出测试方案
5. 不要修改代码

确认方案没有问题后，再允许它实施。

在交互过程中，也可以反复按 Shift+Tab 切换权限模式。当状态栏显示 plan mode on 时，即处于规划模式。

官方说明：Claude Code Plan mode

六、完成第一次代码修改

可以从一个范围较小、容易验证的任务开始。例如：

请在项目主页增加一个健康状态提示。

要求：

1. 复用现有组件和样式
2. 不引入新的依赖
3. 保持现有 API 兼容
4. 添加必要测试
5. 修改完成后运行代码检查和测试
6. 最后总结修改过的文件

Claude Code 会查找相关代码并提出或执行修改。是否需要逐次确认，取决于当前权限模式和项目配置。

修改完成后，不要只问“完成了吗”，而应该要求它提供验证证据：

请检查刚才的修改：

1. 展示 git diff 摘要
2. 运行格式化和代码检查
3. 运行相关测试
4. 如果失败，分析原因并修复
5. 确认没有修改任务范围以外的文件

这种提示词明确了验收标准，能够减少“代码已经生成，但实际上不能运行”的情况。

七、完整的 Bug 修复工作流

假设运行测试时出现错误，可以输入：

运行 npm test 时出现下面的错误：

在这里粘贴完整错误信息。

请先复现问题，定位根本原因，然后给出最小修改方案。
不要通过跳过测试、删除校验或捕获后忽略异常来掩盖问题。

如果已经知道复现步骤，可以一起提供：

复现步骤：

1. 以普通用户登录
2. 打开个人资料页面
3. 清空昵称并提交
4. 页面出现白屏

预期行为：显示昵称不能为空的提示。
实际行为：浏览器控制台出现 TypeError。

请定位并修复，然后添加回归测试。

高质量 Bug 描述最好包含：

复现命令或操作步骤
完整错误信息
预期结果
实际结果
是否稳定复现
可能涉及的文件
不允许采用的临时规避方式

官方也建议提供错误、复现命令和明确的修复范围：Claude Code 常见开发工作流

八、让 Claude Code 记住项目规则

如果每次会话都需要重复说明构建命令、目录结构和编码规范，可以在项目根目录创建 CLAUDE.md。

在 Claude Code 中执行：

/init

Claude 会分析代码库并生成或改进 CLAUDE.md。官方建议将单个文件控制在约 200 行以内，内容保持具体、简洁。

一个简单示例：

# 项目说明

这是一个 TypeScript Web 应用。

## 常用命令

- 安装依赖：`bun install`
- 本地开发：`bun run dev`
- 代码检查：`bun run lint`
- 单元测试：`bun run test`
- 生产构建：`bun run build`

## 修改原则

- 优先复用现有组件。
- 不得在没有说明的情况下增加依赖。
- 用户可见文本必须支持国际化。
- 修复 Bug 时必须添加回归测试。
- 修改完成后运行 lint、test 和 build。

## Git 规则

- 不得覆盖用户现有的未提交修改。
- 未经明确要求，不得执行 `git push`。
- 未经明确要求，不得创建或合并 Pull Request。

CLAUDE.md 适合记录：

构建、测试和格式化命令
目录与架构说明
编码和命名约定
数据库兼容要求
安全限制
提交前必须完成的检查

不适合写入：

API Key
密码
私有 Token
临时任务要求
很长且容易过期的项目介绍

新版 Claude Code 也能够读取 AGENTS.md。但当项目同时存在某些 CLAUDE.md 文件时，默认加载规则会发生变化，可以使用 /context 或 /memory 检查实际加载了哪些指令文件。

官方说明：Claude Code 项目记忆

九、管理文件和命令权限

Claude Code 可以读取文件、编辑代码和执行命令，因此应认真检查权限。

在会话中输入：

/permissions

可以查看和管理三类规则：

Allow：允许执行，不再重复询问
Ask：每次匹配时都需要确认
Deny：阻止执行

权限优先级为：

Deny → Ask → Allow

CLAUDE.md 只是给模型的行为指令，不是安全边界。真正需要阻止的工具或命令，应使用权限规则、沙箱或 Hook 控制。

不要为了省去确认而随意使用：

claude --dangerously-skip-permissions

这个参数会绕过权限提示。除非处于隔离、可丢弃且没有敏感凭证的环境，否则不建议使用。

尤其需要人工确认的操作包括：

删除文件或目录
数据库迁移
修改生产配置
安装未知依赖
git push
强制推送
发布软件包
部署线上环境
向外部服务发送项目内容

官方说明：Claude Code 权限配置

十、常用命令速查

在普通终端中运行

命令	作用
`claude`	启动交互会话
`claude "任务"`	带初始任务启动会话
`claude -p "问题"`	执行一次任务后退出
`claude -c`	继续当前目录最近一次会话
`claude -r`	选择并恢复历史会话
`claude --permission-mode plan`	以 Plan mode 启动
`claude --version`	查看版本
`claude doctor`	检查安装和配置
`claude update`	手动更新
`claude auth status --text`	查看认证状态

例如：

claude "解释这个项目，不要修改文件"

一次性分析：

claude -p "列出项目中的测试命令"

处理命令输出：

npm test 2>&1 | claude -p "分析这些测试错误并按根本原因分类"

在 Claude Code 会话中运行

命令	作用
`/help`	查看当前可用命令
`/clear`	清空当前会话上下文
`/login`	重新登录或切换账户
`/init`	创建或改进项目指令
`/permissions`	管理工具权限
`/memory`	查看和管理记忆
`/context`	查看上下文使用情况
`/model`	查看或切换模型
`/status`	查看账户和使用状态
`/exit`	退出会话

完整参数以当前安装版本中的 claude --help 和官方 CLI 参考为准。

十一、推荐的提示词结构

一个效果稳定的任务通常包含六部分：背景、目标、范围、约束、验证和交付。

背景：
这是一个 React + TypeScript 项目。

目标：
修复用户保存设置后页面没有更新的问题。

范围：
只检查用户设置页面、状态管理和相关 API 调用。

约束：
- 不增加依赖
- 不改变后端接口
- 保持现有 UI 风格
- 不修改无关代码

验证：
- 添加回归测试
- 运行 lint、test 和 build
- 展示测试结果

交付：
总结根本原因、修改文件、验证结果和剩余风险。

较弱的提示词：

帮我修一下。

更好的提示词：

用户修改头像后，页面仍显示旧头像，刷新后才更新。

请先复现并跟踪从上传响应到前端状态更新的完整流程，找出根本原因。
使用最小修改修复，不要通过强制刷新页面规避。
添加覆盖该场景的回归测试，并运行相关检查。

十二、安全与隐私注意事项

使用 Claude Code 前，应确认项目是否允许向模型服务发送代码和上下文。

建议遵循以下原则：

不要把密码、私钥或生产 Token 写进提示词。
.env 中不应保存不必要的长期凭证。
授权命令前先阅读完整命令和目标路径。
修改后通过 git diff 检查实际变化。
高风险修改先使用 Plan mode。
在独立分支或 Git worktree 中处理大型任务。
不要允许 Claude 绕过失败测试或关闭安全检查。
在提交前进行人工代码审查。

十三、常见问题

1. 安装后提示 `claude: command not found`

先关闭并重新打开终端，然后执行：

claude --version

如果仍然失败，运行：

claude doctor

通常是安装目录没有加入 PATH。

2. Claude Code 为什么没有使用我的订阅额度？

检查环境变量中是否设置了 API Key：

printenv ANTHROPIC_API_KEY

Windows PowerShell：

$env:ANTHROPIC_API_KEY

如果存在该变量，Claude Code 可能优先使用 API 认证并产生 API 费用。确认不需要后，应在相应 shell 配置中移除，而不是仅隐藏终端输出。

3. Claude 修改了太多文件怎么办？

先停止继续执行，然后输入：

请不要再修改文件。分析当前 git diff，区分任务必要修改和无关修改，不要覆盖我原本存在的未提交内容。

使用 Git 前先确认哪些修改属于自己，避免直接运行会丢失数据的恢复命令。

4. Claude 没有遵守 `CLAUDE.md`

执行：

/context

检查该文件是否出现在 Memory files 中。同时确保规则简短、具体，没有互相冲突。

5. 如何减少不必要的消耗？

每个会话只处理一个明确目标。
先缩小文件和模块范围。
不要反复粘贴整个代码库。
无关的新任务使用 /clear 后重新开始。
把稳定的项目规则写入 CLAUDE.md。
使用 /model 选择与任务难度相匹配的模型。
API 计费用户可以查看会话成本；订阅用户可通过 /status 关注使用状态。

十四、推荐的日常工作流程

以后使用 Claude Code，可以固定采用下面的流程：

进入正确的项目目录。
检查 git status，确认已有修改。
启动 Claude Code。
让 Claude 先阅读项目规则和相关代码。
对复杂任务使用 Plan mode。
审核实施方案。
允许执行最小范围修改。
运行格式化、代码检查、测试和构建。
人工检查 git diff。
确认无误后再提交代码。

可以直接使用这段提示词：

请完成下面的任务：

【任务】
在这里填写需求。

【工作方式】
1. 先阅读项目说明和相关代码
2. 检查当前 git 状态，保留已有修改
3. 先说明根本原因和实施方案
4. 仅修改完成任务所需的代码
5. 遵循项目现有架构和代码风格
6. 添加或更新有意义的测试
7. 运行格式化、代码检查、测试和构建
8. 最后总结修改文件、验证结果和剩余风险

未经我明确许可，不要执行 git push、部署、发布或破坏性命令。

总结

掌握 Claude Code 的关键并不是让它一次生成更多代码，而是建立清晰的循环：

理解项目 → 明确约束 → 制定方案 → 小步修改 → 自动验证 → 人工审查

按照这个流程使用，Claude Code 才会从“代码生成工具”逐渐变成可靠的开发协作者。

如果你在安装或使用过程中遇到问题，可以在评论区留下操作系统、Claude Code 版本、安装方式和完整错误信息。请务必先删除日志中的 Token、邮箱及其他敏感信息。

Claude Code 完整入门教程：从安装到完成第一次代码修改