Claude Code 完整使用教程

从安装、登录到在真实项目里改代码、跑测试、提交 Git，完整讲清 Claude Code 的使用流程，并说明权限模式、项目级 CLAUDE.md 配置与容易踩的几个坑。

Claude Code 是什么

它是一个跑在终端里的编程智能体：你用自然语言描述任务，它自己检索项目文件、编辑代码、执行命令、读取输出，直到任务完成。和代码补全类工具的区别在于介入位置——补全工具帮你写下一行，Claude Code 接管的是「查清楚、改完、验证过」这一整段。

除命令行外，同一个账号还可以在桌面应用、VS Code 与 JetBrains 插件、网页版以及 CI 集成中使用。本文讲的是命令行，也是功能最完整的入口。

开始之前

三件事缺一不可。

账号。 Pro、Max、Team、Enterprise 订阅，或使用预付额度的 Claude Console 账号。免费的 Claude.ai 方案不包含 Claude Code。企业还可以走 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

运行环境。 macOS 13.0 及以上、Windows 10 1809 及以上、Ubuntu 20.04 / Debian 10 / Alpine 3.19 及以上，4 GB 以上内存。只有 npm 安装方式才要求 Node.js 22 及以上，原生安装不依赖机器上的 Node。

网络。 需要能访问 api.anthropic.com、claude.ai、claude.com、platform.claude.com 与 downloads.claude.ai。这几个域名任意一个被拦，表现都不一样：装不上、登不上，或者装好了发不出请求。

安装

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

分不清自己在哪个终端时看提示符：PowerShell 是 PS C:\，CMD 是没有 PS 的 C:\。在 PowerShell 里执行 CMD 那条命令会报 not a valid statement separator，反过来在 CMD 里执行 PowerShell 那条会报 irm is not recognized。

也可以用包管理器安装：

brew install --cask claude-code

winget install Anthropic.ClaudeCode

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

三点需要注意。第一，npm 包装的是同一个原生二进制文件，不是「Node 版本」，安装后运行的 claude 不会调用你的 Node。第二，不要用 sudo 执行全局 npm 安装，会带来权限与安全问题。第三，安装方式决定更新方式：原生安装后台自动更新，Homebrew、WinGet 与 apt / dnf / apk 都需要手动升级。

安装完成后关闭并重新打开终端。这一步经常被跳过，也是「装完却找不到命令」最常见的原因。

更新

claude update

原生安装平时会自己在后台更新，这条命令只是让更新立刻生效。Homebrew 用 brew upgrade claude-code，WinGet 用 winget upgrade Anthropic.ClaudeCode。

验证与登录

先确认命令可用：

claude --version

正常会输出类似 2.1.211 (Claude Code) 的内容。想看更完整的诊断——安装是否健康、设置文件有没有语法错误、上一次自动更新的结果——运行：

claude doctor

它是只读的，不会启动会话，也不会改动任何配置。

然后直接运行 claude，首次启动会引导登录，在浏览器里完成认证即可。之后要换账号或重新认证，在会话里输入 /login。

几种容易卡住的登录场景：

• 浏览器没有自动打开。 在登录提示处按 c 复制 OAuth 链接，粘贴到浏览器里打开。
• WSL2、SSH 或容器环境。 浏览器开在另一台机器上，回调回不来。登录后页面会给一串登录码，粘回终端提示处即可；粘贴不进去时改用 claude auth login，它从标准输入读取登录码。
• 提示登录码无效。 登录码过期或复制不全，重新走一遍并尽快完成。

在项目里启动

cd /path/to/your/project
claude

启动目录很关键。 它以当前目录为工作范围，在仓库根目录启动才能看到完整结构；在 src/components/ 里启动，它对项目全貌的判断就会缺一大块。确实需要访问其他目录时用 --add-dir 显式加入，而不是跑到更上层的目录去启动。

第一次进去，先让它读，不要急着让它改：

这个项目是做什么的？主要目录结构是怎样的？

移动端导航的实现在哪几个文件里？

如果它对项目的描述明显不对，通常不是模型的问题，而是启动目录错了。

让它修改代码

描述任务的方式直接决定结果质量。有效的描述包含三部分：目标、范围、验收标准。

不好的写法：

优化一下导航

可用的写法：

当前 Astro 项目的移动端导航在 430px 以下会把 logo 挤出容器。
请检查 src/components/layout/ 下的导航组件与相关样式，修复这个溢出，
不要改动桌面端断点的表现，改完运行 npm run build 确认构建通过。

第二种写法给了它可以自己判断「做完了没有」的依据。它会先定位相关文件、说明打算怎么改，然后执行修改。

一次只推进一个明确目标。跨模块的大改动拆成几步分别交付，出问题时更容易回退，审阅成本也低得多。

让它执行命令与验证

不要只看代码「像是对的」，让它跑项目自己的命令：

运行 npm run build，如果失败就修到通过

它会执行命令、读取输出、按报错继续修。这是它和纯对话式助手最大的差别——验证结果来自真实输出，而不是推测。

和 Git 一起用

Git 操作可以直接用自然语言表达：

我改了哪些文件？

新建一个分支 feature/mobile-nav

把当前改动提交，说明修复了移动端导航溢出

一个务实的习惯：动手前先建分支或提交一次检查点。让它工作在可回退的状态上，比事后逐行核对省事得多。

权限：它什么时候会问你

权限模式决定哪些动作不需要你确认。常用的几种：

模式	不询问即可执行	适合
Manual（配置值 default）	只有读取	敏感项目、不熟悉的代码
acceptEdits	读取、文件编辑与常见文件系统命令	你正在逐步审阅的迭代
plan	读取，先出方案再动手	改动前先摸清代码库
auto	几乎全部，由分类器代替人审核	长任务、减少打断
bypassPermissions	全部	仅限隔离的容器或虚拟机

Pro、Max、Team 方案的交互式终端会话默认从 auto 模式开始，其他方案默认 Manual。会话中随时按 Shift+Tab 切换，也可以在启动时指定：

claude --permission-mode default

有几类动作任何模式都不会自动放行，包括被显式 ask 规则匹配的工具、需要用户交互的工具，以及针对关键路径的删除命令。

拿不准的时候用 Manual。多按几次确认，比事后从 Git 里捞回被覆盖的文件便宜。

项目级配置

CLAUDE.md

每次会话都是全新的上下文，CLAUDE.md 是让约定跨会话生效的方式。生成一份初始文件：

/init

它会分析代码库，写出构建命令、测试方式、目录约定等内容；文件已存在时不会覆盖，而是给出改进建议。

生成之后补上它自己看不出来的东西：为什么某个模块不能动、提交前必须跑什么、哪些目录是自动生成的。写作要点只有两条，具体和短：

• 写「使用 2 空格缩进」，不要写「格式化代码」
• 写「提交前运行 npm test」，不要写「测试你的改动」
• 单个文件控制在 200 行以内，太长会稀释效果

文件位置按作用范围区分：~/.claude/CLAUDE.md 是你个人所有项目通用的偏好；./CLAUDE.md 或 ./.claude/CLAUDE.md 是随仓库共享给团队的项目约定；./CLAUDE.local.md 是不进版本库的个人项目备注，记得加进 .gitignore。

仓库里已经有 AGENTS.md 时不必复制一份：在 CLAUDE.md 里写一行 @AGENTS.md 导入即可。

想确认哪些文件真的加载了，在会话里运行 /context，看 Memory files 一栏。

设置文件

.claude/settings.json 放项目级设置，~/.claude/settings.json 放个人设置，权限规则、环境变量、自动更新通道都在这里配置。和 CLAUDE.md 的区别很实际：设置由客户端强制执行，CLAUDE.md 只是写给模型看的上下文。真正要「禁止」某件事，用权限规则或 hook，不要指望在 CLAUDE.md 里写一句话。

一个真实的工作流

以一个普通的 Astro 项目为例，从发现问题到合并：

1. 建分支。 git switch -c fix/mobile-nav，保证可回退。
2. 在仓库根目录启动。 运行 claude。
3. 先定位。 「移动端导航在 430px 以下溢出，相关实现在哪些文件？」确认它找对了地方再往下走。
4. 给出有边界的任务。 说明症状、涉及目录、不能动的部分、验收标准。
5. 审阅改动。 逐个文件看 diff，重点看它有没有顺手改了范围之外的东西。
6. 让它验证。 「运行 npm run build」「在 320、375、430 三个宽度下检查是否还有横向溢出」。
7. 提交。 让它生成 commit message，自己读一遍再确认。
8. 沉淀。 如果这次纠正了它某个反复出错的习惯，把结论写进 CLAUDE.md，下次不用再说一遍。

会话与上下文管理

• /clear：换一个不相关的任务时清空历史，比让它在旧上下文里继续更准。
• /compact：长任务中途压缩上下文，保留结论、丢掉过程。
• claude -c：继续当前目录最近一次会话。
• claude -r 或 /resume：挑一个历史会话恢复。
• claude -p 加一句提问：一次性执行后退出，适合写进脚本。

安全注意事项

• 改动全部经过审阅。 把它的产出当成同事提交的 PR：读一遍、跑测试、有问题打回，而不是直接合并。
• 不要在有敏感数据的目录里启动。 它读到的文件内容会随请求发送给模型。含密钥、客户数据的目录用权限规则排除，或者根本不要放进工作目录。
• bypassPermissions 只在隔离环境里用。 容器或虚拟机之外开这个模式，等于把 shell 无条件交出去。
• 别把密钥写进 CLAUDE.md。 那是会进版本库、也会进上下文的普通文本文件。

连不上、登不上怎么办

装好了却发不出请求、认证一直失败、请求超时——这些属于连接与认证问题，和用法无关，排查路径也完全不同。按服务状态、版本、认证方式、环境变量、代理、DNS、证书的顺序处理，见 Claude Code 连接失败与认证错误排查。

如果是 Claude 网页端或客户端打不开，那是另一类问题，见 Claude 连接失败与网络问题排查。

和 Anthropic API 的关系

Claude Code 是产品，Anthropic API 是接口。用订阅登录时不需要 API Key；用 Claude Console 账号登录时按用量从预付额度扣费，首次登录会自动在 Console 里建一个 Claude Code 工作区用于成本归集。

要把模型接进自己的应用，那是另一件事，见 Anthropic API 快速上手。

和 Codex 怎么选

两者定位接近，差别在生态与工作方式。想同时了解 Cursor 的定位，见 Claude Code vs Codex vs Cursor；想先把 Codex 用起来，见 Codex 完整使用教程。

参考资料

• Claude Code 快速开始（官方文档）
• 安装与环境要求（官方文档）
• 权限模式（官方文档）
• CLAUDE.md 与项目记忆（官方文档）