Claude Code 使用教程：从安装配置到完成第一个真实项目
AI Stack Nav｜从环境准备、账号登录、模型选择到项目落地的保姆级指南
适用对象：AI 编程新手、独立开发者、技术运营、产品经理、前端/后端工程师｜版本：2026 更新版
一、文章摘要
Claude Code 是 Anthropic 推出的 Agentic Coding 工具，它不是普通聊天机器人，而是可以在终端、IDE、GitHub 等开发环境中理解代码库、读取文件、运行命令、修改代码并辅助完成 Git 工作流的开发助手。对于新手来说，Claude Code 的价值不只是“帮你写几行代码”，而是把需求拆解、项目理解、代码生成、错误修复、测试验证和文档输出串成一条完整开发链路。
本文将从安装、登录、模型选择、项目初始化、权限设置、真实项目开发、常见报错排查和开通建议几个方面，带你完成 Claude Code 的第一轮实战。读完后，你应当能独立完成一个小型 Web 项目，并知道什么时候该让 Claude Code 规划、什么时候该让它改代码、什么时候必须人工审查。
| 本文适合你，如果你遇到以下问题： • 听说 Claude Code 很强，但不知道从哪里安装、怎么登录、怎么开始。 • 会用 ChatGPT/Claude 写代码，但不知道如何让 AI 理解整个项目。 • 想用 AI 做一个真实小项目，但担心乱改文件、误删代码或跑不通。 • 已经在用 Cursor、Copilot，想了解 Claude Code 的终端 Agent 工作流。 |
二、Claude Code 是什么？普通新手该怎么理解
2.1 它不是“代码问答工具”，而是终端里的开发 Agent
Claude Code 可以理解为一个“住在开发环境里的 AI 同事”：你用自然语言告诉它目标，它会阅读代码库、查找相关文件、提出修改计划、调用工具修改代码、运行测试，并在必要时继续迭代。官方 GitHub 说明将它定义为一个位于终端中的 agentic coding tool，可以理解代码库并通过自然语言完成例行任务、解释复杂代码和处理 Git 工作流。
✓ 传统 AI 对话：你复制代码进去，AI 返回一段答案，最终还要你手动粘贴。
✓ Claude Code 工作流：AI 直接在项目目录中理解上下文，按权限读写文件并运行命令。
✓ 真正的区别：它从“回答问题”变成“参与执行开发任务”。
2.2 新手最容易误解的 3 件事
| 误解 | 真实情况 | 正确用法 |
| 误解一：装好就能自动做完整项目 | Claude Code 需要明确目标、上下文、约束和验证方式。 | 先写需求，再让它规划，再分步执行。 |
| 误解二：越放开权限越高效 | 权限越大，误操作风险越高，特别是删除文件、改配置、跑脚本。 | 默认询问，复杂任务先用 Plan Mode。 |
| 误解三：AI 写完就等于完成 | AI 生成的代码仍可能有边界遗漏、依赖冲突或业务误解。 | 必须运行测试、构建，并人工 Review 关键逻辑。 |
图 1：Claude Code 从“对话”转向“工具调用 + 结果验证”的开发 Agent 流程
三、安装前准备：系统、账号和基础环境
3.1 你需要准备什么
✓ 一台可正常访问终端的电脑：macOS、Windows、Linux 或 WSL。
✓ 一个可登录 Claude Code 的账号：Claude Pro / Max / Team / Enterprise，或 Claude Console / 云服务商接入方式。
✓ 一个真实项目目录：可以是空项目，也可以是已有代码仓库。
✓ Git 基础环境：建议先安装 Git，便于提交、回滚和查看 diff。
✓ 如果是前端项目，建议准备 Node.js、npm / pnpm；如果是 Python 项目，准备 Python 与虚拟环境。
3.2 不同系统安装方式
官方 Quickstart 文档提供了原生安装、Homebrew、WinGet 等方式。对大多数新手来说，优先使用官方推荐的原生安装脚本；如果你所在环境有公司安全策略，再按团队规范使用包管理器或内部镜像。
| 系统 | 推荐命令 | 说明 |
| macOS / Linux / WSL | curl -fsSL https://claude.ai/install.sh | bash | 适合绝大多数终端环境。WSL 用户建议配合 Git 与 Node 环境。 |
| Windows PowerShell | irm https://claude.ai/install.ps1 | iex | PowerShell 提示符通常以 PS C:\ 开头。 |
| Windows CMD | curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd | 如果 PowerShell 命令不可用，可以切换 CMD。 |
| Homebrew | brew install –cask claude-code | 适合习惯 Homebrew 管理软件的 macOS / Linux 用户。 |
| npm 方式 | npm install -g @anthropic-ai/claude-code | 文档仍提供 npm 安装，但当前官方仓库提示优先使用推荐安装方式。npm 方式需要 Node.js 18+。 |
| # macOS / Linux / WSL 推荐方式 curl -fsSL https://claude.ai/install.sh | bash # Windows PowerShell 推荐方式 irm https://claude.ai/install.ps1 | iex # 安装后检查 claude –version claude |
| 新手注意 • Windows 用户如果提示命令不识别，先确认自己是在 PowerShell 还是 CMD。 • 不要在重要生产项目里第一次试用，先复制一份测试项目或新建分支。 • 如果安装后命令不存在，关闭并重新打开终端，或检查 PATH 是否刷新。 |
四、登录与基础配置
4.1 第一次运行 Claude Code
安装完成后，在终端输入 claude。如果是第一次使用，Claude Code 会尝试打开浏览器完成登录；如果浏览器没有自动打开，可以复制终端中的登录链接到浏览器。官方认证文档说明，个人用户可以通过 Claude.ai 账号登录，团队和企业用户也可以使用 Teams、Enterprise、Claude Console 或云服务商方式接入。
| # 进入你的项目目录 cd /path/to/your-project # 启动 Claude Code claude # 常用账号命令 /login /logout /status |
4.2 建议先做的 5 个配置动作
1. 运行 /login，确保账号状态正常。
2. 运行 /model，查看当前可用模型，选择适合当前任务的模型。
3. 运行 /init，在项目根目录生成 CLAUDE.md，让 Claude 记住项目规则。
4. 运行 /permissions，查看读写文件、执行命令等权限规则。
5. 运行 /config，检查全局和项目级配置是否生效。
4.3 CLAUDE.md 应该写什么
CLAUDE.md 是 Claude Code 理解项目的重要入口。你可以把它看成“项目说明书 + 编码规范 + 常用命令”。新手不要写太长，先覆盖技术栈、启动命令、测试命令、代码风格、禁止事项。
| # 项目说明 这是一个基于 Vite + React + TypeScript 的 AI 工具导航小项目。 # 常用命令 – 安装依赖：npm install – 本地启动：npm run dev – 构建检查：npm run build – 代码检查：npm run lint # 开发规则 – 优先使用 TypeScript，避免 any。 – 修改前先说明计划，复杂改动先进入 plan mode。 – 不要删除现有功能，除非用户明确要求。 – 修改完成后必须运行 npm run build。 |
五、模型选择：Sonnet、Opus、Haiku 怎么用
5.1 不要只看“最强”，要看任务类型
Claude Code 中可选模型会随着账号、地区和产品策略变化而变化，因此实际选择以 /model 面板显示为准。对普通用户来说，模型选择可以按任务难度分层：常规开发用平衡模型，复杂架构和疑难 Bug 用更强模型，文档和轻量整理用更快模型。
| 任务类型 | 建议模型策略 | 典型场景 | 提示词建议 |
| 日常代码生成 | 优先选择平衡型模型 | 组件、接口、脚本、小功能 | “先列计划，再改代码，最后运行构建。” |
| 复杂重构 | 选择更强推理模型 | 跨文件重构、架构调整、性能优化 | “保持行为不变，分阶段重构并补充测试。” |
| 疑难 Bug | 选择更强推理模型 | 测试失败、依赖冲突、边界问题 | “先定位根因，不要直接改，给出证据链。” |
| 文档/注释 | 选择快速或低成本模型 | README、API 文档、注释补全 | “根据代码生成准确文档，不要编造不存在的接口。” |
| 学习解释 | 选择平衡型即可 | 解释项目结构、代码逻辑、函数作用 | “用新手能理解的话解释，并给出文件路径。” |
| 模型选择口诀 • 看不懂项目：先用平衡模型梳理结构。 • 要大改代码：先用 Plan Mode，再用强模型执行。 • 只是写文档：用快速模型，节省额度。 • 任务很长：拆成多个小任务，比一次性让模型全做更稳。 |
六、第一个真实项目：做一个 AI 工具收藏清单页面
6.1 项目目标
为了让新手能真正跑通，这里选择一个轻量但完整的项目：使用 Vite + React + TypeScript 做一个“AI 工具收藏清单页面”。页面包含工具卡片、分类筛选、搜索框、收藏按钮和简单数据文件。这个项目不复杂，但足以覆盖安装、需求拆解、代码生成、调试、构建和文档输出。
图 2：第一个真实项目的 Claude Code 实战流程
6.2 创建基础项目
| # 创建 Vite React TS 项目 npm create vite@latest ai-tools-demo — –template react-ts cd ai-tools-demo npm install # 启动前先初始化 git git init git add . git commit -m “init project” # 启动 Claude Code claude |
6.3 第一步：让 Claude Code 理解项目
不要一上来就让它写完整项目。先让 Claude Code 读取目录，解释当前项目结构，并生成 CLAUDE.md。
| /init 请先阅读当前项目结构，告诉我： 1. 这是一个什么技术栈的项目； 2. 主要入口文件在哪里； 3. 后续如果要做“AI 工具收藏清单页面”，可能会修改哪些文件； 4. 先不要修改任何文件。 |
6.4 第二步：用 Plan Mode 拆需求
Plan Mode 的价值是：先让 Claude 读取上下文和设计方案，不直接触碰源文件。对新手来说，这一步能显著降低“AI 乱改项目”的风险。
| /plan 创建一个 AI 工具收藏清单页面，要求： – 顶部有标题和搜索框； – 工具卡片包含名称、分类、简介、官网按钮； – 支持按分类筛选：写作、图片、视频、编程、办公； – 使用本地数组数据，不接后端； – 保持样式简洁，适合 AI Stack Nav 风格； – 先输出文件修改计划，不要直接改代码。 |
6.5 第三步：确认计划后执行
确认计划没有问题后，再让 Claude Code 分步修改文件。每做完一轮，都要查看 diff，并让它运行构建命令。
| 计划可以，开始执行。 要求： 1. 每次修改后说明改了哪些文件； 2. 保留原项目能正常启动； 3. 完成后运行 npm run build； 4. 如果构建失败，先解释错误原因，再修复。 |
6.6 第四步：让它补文档、提交信息和下一步建议
| 请完成收尾： 1. 生成 README.md，包含项目介绍、安装、启动、构建命令； 2. 总结本次改动； 3. 写一条规范的 git commit message； 4. 给出下一步可扩展功能，例如收藏持久化、标签筛选、详情页。 |
| 交付标准 • npm run build 能通过；页面能正常显示；搜索和筛选可用。 • README 有安装与启动说明；修改文件路径清晰。 • Git diff 可读，没有无关大改、没有误删配置。 • 你能用自己的话解释这个项目如何运行。 |
七、Claude Code 常用命令速查
| 命令 | 用途 | 新手使用建议 |
| /init | 初始化项目说明文件 CLAUDE.md | 第一次进入项目先运行。 |
| /model | 选择当前会话模型 | 复杂任务前检查一次。 |
| /plan | 进入计划模式 | 大改之前必用。 |
| /permissions | 管理工具权限 | 不确定时保持默认询问。 |
| /memory | 查看或管理记忆文件 | 让项目规则沉淀下来。 |
| /hooks | 查看自动化钩子 | 进阶使用，适合自动运行测试或 lint。 |
| /mcp | 管理 MCP 外部工具连接 | 接 GitHub、Figma、数据库前先理解权限风险。 |
| /login / /logout | 登录或退出账号 | 账号异常时使用。 |
7.1 配置目录怎么理解
Claude Code 的配置并不只存在一个地方。官方设置文档将配置分为 Managed、User、Project、Local 等范围：企业策略可以由 IT 管理；个人偏好放在用户目录；团队共享规则放在项目 .claude 目录；个人临时覆盖放在 local 配置中。新手可以先记住两个文件：项目根目录的 CLAUDE.md，以及 .claude/settings.json。
7.2 Hooks、Skills、MCP 什么时候用
| 能力 | 作用 | 适合人群 | 风险提醒 |
| Hooks | 在特定事件自动运行脚本，例如每次修改后跑 eslint。 | 有固定测试流程的开发者/团队。 | Hook 会执行本机命令，必须先审查脚本。 |
| Skills | 把团队知识、规范和固定流程封装成可复用能力。 | 希望标准化输出的团队。 | 不要把密钥写进技能文件。 |
| MCP | 把外部工具连接给 Claude，例如 GitHub、Figma、数据库。 | 需要跨工具自动化的进阶用户。 | 外部工具权限必须最小化。 |
八、权限与安全：新手一定要先学会“刹车”
8.1 权限规则的基本逻辑
Claude Code 的权限系统通常围绕三类规则：允许、询问、拒绝。官方权限文档说明，读文件和搜索通常不需要审批，执行 Bash 命令和修改文件则需要用户批准；你也可以通过 /permissions 查看规则来源与范围。
| 权限类型 | 示例 | 是否建议新手自动批准 | 原因 |
| Read / Grep | 读取文件、搜索代码 | 可以 | 风险较低，主要用于理解项目。 |
| Edit / Write | 修改文件、创建文件 | 谨慎 | 需要查看 diff，避免误改。 |
| Bash | npm install、rm、git reset | 不建议一律放开 | 命令影响范围大，尤其是删除、网络、脚本执行。 |
| MCP 工具 | GitHub、Figma、数据库 | 按工具最小授权 | 可能访问外部数据或生产系统。 |
8.2 推荐安全工作流
1. 每个任务前先 git status，确保当前工作区干净。
2. 复杂任务先用 /plan，不直接允许写文件。
3. 每轮改完查看 diff，再允许继续。
4. 自动执行命令前先看命令内容，尤其是 rm、git reset、curl pipe bash、数据库迁移。
5. 不要把 .env、API Key、账号密码直接贴给 Claude Code。
6. 重要项目使用分支、worktree、容器或虚拟机隔离。
图 3：Claude Code 不同场景下的推荐工作模式与风险控制
九、常见报错与解决方法
| 问题 | 可能原因 | 解决方法 |
| claude 命令不存在 | PATH 未刷新或安装失败 | 重开终端；检查安装日志；重新执行官方安装命令。 |
| 浏览器无法回跳登录 | WSL、SSH、容器环境中本地回调不可达 | 复制登录 URL 到浏览器，按提示把 code 粘回终端。 |
| 模型不可选或额度不足 | 账号套餐、地区、组织策略或额度限制 | 运行 /model 查看可用项；检查订阅或 API 余额。 |
| AI 修改后项目跑不起来 | 需求不清、一次性改动太多、缺少测试 | 回滚到 git checkpoint，拆小任务，让 Claude 先分析错误。 |
| 权限弹窗太多 | 默认模式需要逐次确认 | 对低风险命令设置 allow；高风险命令保持 ask/deny。 |
| 上下文越来越乱 | 会话过长、目标变化太多 | 总结当前状态，开启新会话；更新 CLAUDE.md。 |
| 生成的代码风格不统一 | 没有项目规范或没有读取 lint 配置 | 在 CLAUDE.md 中写清规范，并要求运行 lint。 |
十、适合哪些用户？不适合哪些用户？
10.1 适合使用 Claude Code 的人群
✓ 已经有基本终端和 Git 使用经验，想提升开发效率的个人开发者。
✓ 正在学习前端、Python、自动化脚本，希望 AI 带着做真实项目的新手。
✓ 需要快速理解老项目、补文档、修 Bug 的技术运营或产品技术岗。
✓ 希望把 AI Agent 接入研发流程的创业团队和小型技术团队。
10.2 暂时不建议直接上手的人群
✓ 完全不会终端，也不了解文件路径和项目目录的新手，应先学习基础命令。
✓ 项目里有大量生产密钥、客户数据、敏感代码，且没有隔离环境。
✓ 只想一次性生成完整商业系统，不愿意做测试、Review 和迭代。
✓ 没有明确需求，只希望 AI “自己想一个项目并完成全部上线”。
十一、FAQ
Q1：Claude Code 必须会编程才能用吗？
不必须，但至少要懂项目目录、终端命令、Git 提交和报错信息。完全零基础也能跟着做小项目，但不能把它当成无需理解的“自动开发机器”。
Q2：Claude Code 和 Cursor 有什么区别？
Cursor 更像带 AI 的编辑器，适合图形化写代码；Claude Code 更强调终端 Agent 工作流，适合读取项目、运行命令、处理跨文件任务。实际可以组合使用。
Q3：新手应该用哪个模型？
以 /model 面板可用项为准。一般先用平衡模型做日常开发，复杂重构或疑难 Bug 再切换更强模型。
Q4：它会不会误删文件？
有可能，所以不要随便放开高风险权限。重要项目要先提交 Git，复杂任务用 Plan Mode，并逐步确认 diff。
Q5：Claude Code 能做完整网站吗？
可以辅助完成小型网站或模块，但你仍需要明确需求、确认设计、处理部署、测试安全和后续维护。
Q6：公司项目能不能直接用？
取决于公司合规、数据安全和授权策略。建议先询问团队或管理员，使用 Team/Enterprise 或内部规定的接入方式。
Q7：为什么它有时会跑偏？
常见原因是上下文太长、需求不明确、项目规则缺失或一次性任务过大。把需求拆小、更新 CLAUDE.md、要求先规划，会明显改善。
Q8：是否值得付费？
如果你经常写代码、修 Bug、读项目或做自动化，Claude Code 的价值很高；如果只是偶尔问几段代码，普通聊天工具可能已经够用。
十二、总结：Claude Code 的核心不是“更会写代码”，而是“更会参与开发流程”
Claude Code 真正改变的是开发协作方式：过去 AI 只能给你答案，现在它可以进入项目，围绕文件、命令、测试和 Git 工作流协助完成任务。新手第一次上手时，不要追求“一句话生成完整应用”，而要建立标准流程：明确需求、初始化记忆、先规划、分步执行、运行验证、人工 Review。
只要你把 Claude Code 当成“可控的开发 Agent”，而不是“无监督自动程序员”，它就能在学习、个人项目、公司内部工具、文档维护和快速原型开发中提供非常明显的效率提升。
参考资料
Claude Code Quickstart：https://code.claude.com/docs/en/quickstart
Claude Code Setup：https://code.claude.com/docs/en/setup
Claude Code Authentication：https://code.claude.com/docs/en/authentication
Claude Code Commands：https://code.claude.com/docs/en/commands
Claude Code Permissions：https://code.claude.com/docs/en/permissions
Claude Code Settings：https://code.claude.com/docs/en/settings
Claude Code Common Workflows：https://code.claude.com/docs/en/common-workflows
Claude Code Best Practices：https://code.claude.com/docs/en/best-practices
Anthropic Claude Code GitHub：https://github.com/anthropics/claude-code
Anthropic Claude Pricing：https://claude.com/pricing
