Claude Code 从安装到上手完整指南：写代码、改仓库与跨场景辅助

Claude Code 是 Anthropic 推出的 agentic 编程工具：同一套能力覆盖终端 CLI、VS Code / Cursor / JetBrains 扩展、桌面应用，以及浏览器与移动端上的 Web / Remote…

作者：小白 ·

Claude Code 是 Anthropic 推出的 agentic 编程工具：同一套能力覆盖终端 CLI、VS Code / Cursor / JetBrains 扩展、桌面应用，以及浏览器与移动端上的 Web / Remote 协同。它不只「给几行补全」，而是能读仓库、改多文件、跑命令、走 Git / PR，并在权限模式与 hooks 约束下把任务推进到可验收结果。本文按「它是什么 → 安装 → 登录与权限 → 日常写代码 → 文档与跨场景辅助 → 自动化与进阶 → 官方入口」展开，尽量写细，方便对照上手。

Claude Code 安装示意

一、Claude Code 是什么：先建立正确预期

可以把 Claude Code 理解成「能在你项目目录里干活的工程助手」，而不是「只会聊天的补全插件」。

1. 同一引擎，多种表面

| 入口 | 适合谁 | 典型用途 |
| --- | --- | --- |
| 终端 CLI | 习惯命令行、要进脚本/CI 的人 | 本地交互改码、管道无头执行、流水线 |
| VS Code / Cursor 扩展 | 长期泡在编辑器里的人 | 内联 diff、@ 文件、计划审阅、会话历史 |
| JetBrains 插件 | IDEA / PyCharm / WebStorm 用户 | 交互 diff、选区上下文共享（需另装 CLI） |
| Desktop 桌面端 | 想可视化盯多会话的人 | 并排会话、看 diff、调度例行任务、拉起云端会话 |
| Web / 移动端 | 不方便本机、要长任务异步的人 | 浏览器发起任务、手机续跑、远程协作 |

各入口共享同一套 Claude Code 引擎：项目里的 CLAUDE.md、设置与 MCP 服务器可跨表面复用。订阅方面，多数入口需要 Claude 订阅（Pro / Max / Team / Enterprise）或 Anthropic Console；终端 CLI 与 VS Code 也支持部分第三方 / 企业云提供商（以官方当前说明为准）。

2. 它擅长什么

  • 跨文件实现功能、重构、修 bug，并根据测试失败继续迭代
  • 用自然语言驱动 Git：暂存、写提交说明、建分支、开 PR
  • 先出计划再改代码（Plan 模式），降低误改风险
  • 通过 MCP 连接文档、工单、设计稿等外部上下文
  • 用 Skills / hooks / 多 Agent 把重复流程标准化、并行化
  • 把日志、diff、变更文件列表管道进 CLI，做审查与自动化

3. 它不替代什么

  • 不替代你对业务目标、上线窗口与风险的最终判断
  • 不替代代码审查里的人工拍板
  • 不保证「一句提示就完美」——需要审查 diff、补充约束、必要时回滚重来

多入口协同示意

二、安装：CLI 优先，再补 IDE / 桌面 / Web

建议至少装通 CLI + 一个编辑器扩展；Web 用浏览器打开即可，不必本机再装。

1. 安装 Claude Code CLI（官方推荐：原生安装器）

原生安装器不依赖 Node.js，且会后台自动更新，是目前官方主推方式。npm 全局安装路径已标记为废弃，新环境尽量别再走 npm。

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 里却用了 CMD 写法；若 irm 不被识别，则是在 CMD 里却用了 PowerShell 写法。提示符带 PS C:\ 多为 PowerShell，不带 PS 多为 CMD。

原生 Windows 建议安装 Git for Windows，以便 Claude Code 使用 Bash 工具；未安装时会回退到 PowerShell。WSL 内按 Linux 方式安装即可，不必再装 Git for Windows。

其他安装渠道：

# Homebrew（macOS / Linux）
brew install --cask claude-code
# 更跟新的通道：
# brew install --cask claude-code@latest

# WinGet（Windows）
winget install Anthropic.ClaudeCode

Homebrew / WinGet 不会自动更新，需要定期 brew upgrade / winget upgrade。Debian / Fedora / RHEL / Alpine 等也可走 apt / dnf / apk（细节见官方 Advanced setup）。Alpine 等 musl 环境可能要先装 bash、curl、libgcc 等运行时依赖。

装好后验证：

claude --version
claude doctor

进入任意项目：

cd your-project
claude

首次运行会引导登录。

2. 安装 IDE 扩展

  • VS Code / Cursor：扩展市场搜索「Claude Code」安装；命令面板输入 Claude Code，选择在新标签页打开。
  • JetBrains：从 JetBrains Marketplace 安装 Claude Code 插件并重启 IDE；插件依赖单独安装的 CLI。

IDE 的价值是：改动直接落在工作区，diff 更直观，适合「边看文件边指挥 Agent」。

3. 桌面应用（可选）

从官方下载 macOS（Intel / Apple Silicon）或 Windows（x64 / ARM64）安装包，登录后进入 Code 相关入口即可。适合并排看多会话、可视化审 diff、调度例行任务。通常需要付费订阅。

4. Web（浏览器 / 手机）

打开 https://claude.ai/code，无需本机装 CLI 即可发起长任务、并行任务，或处理本机没有的仓库。适合开会间隙盯进度、手机续跑，再用 claude --teleport 等能力把云端会话拉回终端（具体能力以订阅与当前文档为准）。

三、登录、权限与第一次安全配置

首次配置示意

1. 登录方式

启动 claude 后按提示在浏览器完成鉴权。会话内可用 /login 切换账号或重新登录。常见账号类型：

  • Claude Pro / Max / Team / Enterprise（个人与团队日常推荐）
  • Claude Console（API 预付费额度；首次登录常会自动创建用于成本归集的 Claude Code workspace）
  • 企业云：Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 等（需企业侧配置）
  • 自建 / 企业网关：由管理员预配网关地址，经 SSO 登录

凭证会保存在本机，之后一般不必每次重登。

2. 权限模式：先搞懂「改文件要不要问你」

Claude Code 会按权限模式决定是否在改文件前征求确认。默认偏安全：每次改动先问。会话里可用 Shift+Tab 在模式间切换（文案随版本可能微调）：

| 模式（概念） | 含义 |
| --- | --- |
| 默认 / 逐次确认 | 改文件前先问你（新手推荐起点） |
| acceptEdits | 自动批准文件编辑，仍可能对高风险命令更谨慎 |
| plan | 先给方案与涉及文件，不直接动代码 |
| auto（部分账号） | 后台安全检查；反复触发风险拦截后会回到更保守提示 |

本地新手建议：先默认确认 → 熟悉 diff 风格后再开 acceptEdits；大重构仍优先 plan。

3. 项目级指令：CLAUDE.md

在仓库根目录放 CLAUDE.md（也可按目录分层），Claude Code 每次会话开始都会读。适合写：

  • 编码规范与禁止事项（例如「不要升级主版本依赖」）
  • 架构约定、目录职责
  • 常用构建 / 测试命令
  • 审查清单（安全、可访问性、i18n）

它还会在工作过程中积累自动记忆（如构建命令、排障经验），减少你每次重复口述。

4. 第一次验证清单

  1. claude --version 有输出，且标注 Claude Code
  2. claude 能进入交互界面并完成登录
  3. 在练习仓库里先问「这个项目做什么 / 技术栈是什么」，确认它会读仓而不是瞎猜
  4. 再给一个小改动，确认你会看到审批或 diff
  5. 试一下 /help 与 Shift+Tab，知道命令与权限切换在哪

四、日常写代码：从交互会话到无头管道

终端 Agent 示意

1. 交互模式（最常用）

cd your-project
claude

好提示通常包含四件事：

  • 目标：要完成什么
  • 范围：哪些目录可以动 / 不能动
  • 验收：如何证明做完（测试命令、页面路径、接口行为）
  • 约束：不要改 CI 密钥、不要大范围格式化无关文件等

示例：

给 user 模块补上邮箱格式校验：
1) 修改校验函数与对应单测
2) 跑相关测试并修到通过
3) 不要改无关模块
4) 最后用中文写一段变更说明

也可以一次性启动就带上任务：

claude "write tests for the auth module, run them, and fix any failures"

2. 常用 Shell 启动参数

| 命令 | 作用 |
| --- | --- |
| claude | 进入交互模式 |
| claude "任务" | 带初始任务启动 |
| claude -p "查询" | 单次查询后退出（适合脚本） |
| claude -c | 继续当前目录最近一次会话 |
| claude -r | 恢复历史会话 |

3. 会话内斜杠命令（提高操控感）

在交互界面输入 / 可调出命令（列表随版本变化，以 /help 为准），常见用途包括：

| 命令（示例） | 作用 |
| --- | --- |
| /help | 查看可用命令 |
| /login | 重新登录 / 切换账号 |
| /clear | 清空当前对话历史 |
| /resume | 继续先前对话 |
| /schedule | 配置例行任务（以当前版本为准） |
| /desktop | 把当前终端会话转到桌面端继续（平台支持时） |
| /exit | 退出（也可 Ctrl+D 两次） |

大改动前先切到 plan 或明确要求「先列计划与文件清单，我确认后再改」，能减少上来就改炸的概率。

4. 无头模式与 Unix 管道：给脚本和 CI 用

Claude Code 遵循可组合的 CLI 习惯，适合把日志、变更列表喂进去：

# 分析最近日志
tail -200 app.log | claude -p "如果发现异常，用条目列出严重级别与建议"

# CI 里对变更做安全初审
git diff main --name-only | claude -p "review these changed files for security issues"

# 批量翻译并提 PR（概念示例）
claude -p "translate new strings into French and raise a PR for review"

适合：GitHub Actions / GitLab CI 自动初审、定时巡检、批量检查。不适合无人值守直接合并到生产。

代码修改与 diff 示意

5. IDE 里写代码的推荐节奏

  1. 打开正确仓库与分支
  2. 用 Claude Code 面板描述任务（可 @ 文件 / 选区）
  3. 看着它改文件，逐个确认 diff
  4. 本地跑测试或启动服务验证
  5. 让它起草 commit message，你再精修后提交

6. 代码任务分层（避免一次塞太多）

| 层级 | 例子 | 建议 |
| --- | --- | --- |
| 小 | 改一个函数、补日志 | 直接交互执行 |
| 中 | 一个小功能跨 3–5 文件 | 先 plan，再执行 |
| 大 | 模块迁移、鉴权改造 | 拆成里程碑，每步可回滚；可考虑多 Agent 分工 |

7. 与 Git / PR 协作

自然语言即可驱动常见流程：

what files have I changed?
commit my changes with a descriptive message
create a new branch called feature/quickstart
help me resolve merge conflicts

在 CI 中还可配合 GitHub Actions / GitLab CI 做 PR 审查与 issue 分流；Slack 里 @Claude 报 bug 再回收 PR 的链路也适合「异步协作」场景（以团队开通能力为准）。

8. 审查清单（每次都该过一眼）

  • 是否改到了范围外的文件？
  • 是否引入了秘密信息（密钥、token、内网地址）？
  • 测试是否真的跑过，还是只写了「应该可以」？
  • 错误处理与边界条件有没有被简化掉？
  • CLAUDE.md / README / changelog 要不要同步？

五、不止写代码：文档、知识与其他领域辅助

文档与知识工作示意

Claude Code 的「工程能力」迁移到其他文字与流程工作时，关键是：给真实上下文 + 明确产出物格式 + 禁止编造。

1. 写与改技术文档

适用：README、docs/、接口说明、迁移指南、Onboarding。

请阅读 package.json 与实际目录，更新 docs/getting-started.md：
- 安装与启动步骤分 macOS/Windows/Linux
- 列出真实存在的 npm scripts
- 增加 5 条常见报错与处理
- 不确定的地方标 TODO，不要编造命令

2. 生成变更说明与发布说明

根据当前 git diff 写一份面向非技术人员的更新说明：
- 用户能感知的变化
- 风险与回滚建议
- 不要提无关重构细节

3. 代码审查与安全初检

审查这次变更：关注注入、权限绕过、敏感日志、错误的缓存键。
输出：问题列表（严重级别 + 文件位置 + 复现/影响 + 修复建议）

4. 测试与质量辅助

  • 为未覆盖模块补单测
  • 把失败日志贴进去，让它定位并修到绿灯
  • 生成最小复现说明，方便同事接力

5. 数据分析 / 脚本辅助（工程向）

不一定替代专业 BI，但很适合：

  • 写数据清洗脚本
  • 解释一段 SQL / pandas 逻辑
  • 把口头统计需求落成可运行脚本草稿

务必要求：标注假设，不要假装已经跑过真实数据结果。

6. 运营、协作与方案文档（谨慎使用）

可用于：

  • 把会议要点整理成行动项（你提供原始笔记）
  • 把 API 变更翻译成对业务同学的说明
  • 写 RFC / 技术方案骨架（你负责拍板与事实核对）

不建议：在无事实来源时让它编造竞品数据或未发生的进度。

7. 用 MCP 把「查资料 → 改代码 → 回写说明」串起来

MCP（Model Context Protocol）可让 Claude Code 读取 Google Drive 设计文档、更新 Jira、拉取 Slack 上下文，或接入你们自建工具。接入原则：权限最小化——只开只读或明确需要的写权限，避免把生产写权限随手交给 Agent。

8. 把重复流程变成 Skills 与 Hooks

  • Skills：把「发版检查」「日志排查」「文档结构」等打成可复用技能（如 /review-pr、/deploy-staging），团队共享，减少提示词漂移。
  • Hooks：在编辑后自动格式化、提交前跑 lint 等，用生命周期钩子把质量门禁嵌进 Agent 动作前后。

六、多 Agent、云端、定时与自动化

流水线与自动化示意

1. Agent 团队与并行会话

可让主 Agent 拆分子任务，多个子 Agent 在共享文件系统上并行推进，再汇总结果。桌面端适合并排盯多条会话；长时间互不阻塞的改造，也适合拆成并行线程。

2. 云端任务什么时候更香

  • 本机要开会，但任务很长
  • 需要同时推进多个改造
  • 仓库不在本机，或希望结果直接落到 PR 异步审查
  • 用手机 / 浏览器续跑，再拉回终端继续

3. Routines / 定时与事件

可把重复工作配成例行：早间 PR 审查、夜间 CI 失败分析、周依赖审计、合并后同步文档等。

  • Routines：可跑在 Anthropic 托管基础设施上，电脑关机也能继续；也可由 API / GitHub 事件触发
  • 桌面定时任务：跑在本机，直接访问本地文件与工具
  • 会话内 /loop：在单次 CLI 会话里轮询式重复提示（适合短周期探测）

4. CI 中的定位

把 claude -p 嵌进流水线，适合「自动初审」与「失败日志摘要」，不适合无人值守直接合并生产。高风险仓库务必保留人类审查门禁。

5. Agent SDK（进阶）

若要把 Claude Code 的工具能力嵌进你们自己的编排系统，可关注官方 Agent SDK：自行控制编排、工具权限与审批策略，适合平台团队做内部编码 Agent。

七、推荐学习路径（两周）

第 1–2 天：装通 + 只读

  • 安装 CLI 与一个 IDE 扩展
  • 用「解释项目结构 / 技术栈」熟悉输出风格
  • 写一份最小 CLAUDE.md（构建命令 + 三条规范）

第 3–5 天：小改动闭环

  • 每天完成 1 个「单测级」小任务
  • 强制自己审查每一个 diff
  • 练习 Shift+Tab 在确认 / acceptEdits / plan 间切换

第 6–10 天：中等功能

  • 先 plan 后执行
  • 同步更新 README 一小节
  • 试一次用自然语言完成 commit

第 11–14 天：流程化

  • 沉淀 1–2 个 Skills（例如审查 PR、写发布说明）
  • 试一条 CI 初审或 hooks（格式化 / lint）
  • 整理自己的高频提示词模板

八、常见问题

Q：Claude Code 和 Cursor / Codex 怎么选？
A：没有唯一答案。Claude Code 强在 Anthropic 模型与多表面统一的 agentic CLI；Cursor 是 AI 原生 IDE 体验；Codex 强在 OpenAI 生态。可按团队已有订阅与工作流选择，也可以组合使用。

Q：为什么它改得很勤但不对？
A：多半是目标含糊或缺少验收命令。把「做什么 / 不做什么 / 如何验证」写清楚，并先让它探索代码再动手，成功率会明显上升。

Q：npm 安装还可以用吗？
A：官方已标记 npm 全局安装为废弃路径，新环境请用原生安装器 / Homebrew / WinGet。旧环境可按文档迁移到原生二进制。

Q：可以一直开自动批准吗？
A：可以，但只建议在练习仓或高度隔离环境；主仓库建议保留人工确认，尤其是涉及密钥、权限、生产配置时。

九、官方入口

十、小结

  1. 先装原生 CLI，再补 IDE 扩展；Web / 桌面按需启用。
  2. 登录优先 Claude 订阅；权限上先「逐次确认」，大改动用 plan。
  3. 写代码：交互做日常，plan 控大改，-p 进脚本/CI；每次看 diff。
  4. 写文档与其他辅助：给真实仓库上下文，禁止编造，产出物格式写死。
  5. 用 CLAUDE.md + Skills + hooks + MCP 把个人技巧变成团队提效。

查看完整讨论与评论