# Claude Code 零基础入门：从安装到第一个项目 > **学习目标**：零基础掌握 Claude Code 的安装、认证、核心配置，并完成第一个 Web 应用的构建。 > > **适用人群**：有基本终端操作经验的开发者、编程学习者、技术管理人员。无需 AI 编程工具使用经验。 --- ## 一、Claude Code 是什么 Claude Code 是 Anthropic 官方推出的 AI 编程助手，以 CLI（命令行界面）形式运行在终端中。它不同于浏览器中的 ChatGPT 或 Claude.ai——Claude Code 直接嵌入你的开发环境，能够读取文件、编辑代码、执行命令、管理 Git，甚至部署项目。  > *图表 1* **核心能力一览**： | 能力 | 说明 | |------|------| | 文件理解 | 读取任意大小代码库，理解项目结构 | | 代码编辑 | 精准定位并修改代码，非暴力覆盖 | | 命令执行 | 在沙盒中运行构建、测试、部署命令 | | Git 集成 | 提交、创建分支、管理 PR | | MCP 扩展 | 通过 Model Context Protocol 连接外部工具 | | Skills 技能系统 | 加载预定义的专业工作流 | | 子代理 | 并行分派多个子任务同时执行 | **版本信息**：截至 2026 年 5 月，Claude Code 最新版本为 **2.1.x** 系列，支持终端 CLI、桌面应用、VS Code 集成和 Web 版本。本教程聚焦终端 CLI，这是功能最完整的使用方式。 --- ## 二、环境准备 ### 2.1 系统要求 | 项目 | 最低要求 | |------|----------| | 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+（WSL2 或原生） | | Node.js | **18.0+**（推荐 20.x LTS） | | npm | 随 Node.js 自带 | | 内存 | 建议 8GB+ | | 网络 | 需要访问 Anthropic API 或代理服务 | ### 2.2 安装 Node.js 如果你的系统还没有 Node.js 18+，推荐使用 `nvm`（Node Version Manager）安装： ```bash # 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 Node.js 20 LTS nvm install 20 nvm use 20 # 验证安装 node --version # 应输出 v20.x.x npm --version # 应输出 10.x.x ``` **Windows 用户**可使用 winget 快速安装： ```powershell winget install OpenJS.NodeJS.LTS ``` 或者通过 WSL2 中的 Ubuntu 环境，按照上述 Linux 步骤操作。 ### 2.3 安装 Claude Code ```bash # 全局安装（推荐） npm install -g @anthropic-ai/claude-code # 验证安装成功 claude --version # 输出类似: 2.1.56 (Claude Code) ``` 如果遇到权限问题（Linux/macOS），**不要使用 `sudo`**，改用： ```bash # 方案1：使用 nvm 安装的 Node.js（推荐，无需 sudo） npm install -g @anthropic-ai/claude-code # 方案2：修改 npm 全局目录 mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm install -g @anthropic-ai/claude-code ``` --- ## 三、认证与启动 ### 3.1 认证方式 Claude Code 支持两种认证方式： **方式一：Anthropic 账号登录（推荐）** ```bash claude auth # 会打开浏览器，引导你登录 Anthropic 账号 ``` **方式二：API Key 认证** ```bash # 设置环境变量（写入 ~/.bashrc 或 ~/.zshrc） export ANTHROPIC_API_KEY="sk-ant-xxxxx" # 或者使用 Claude 的 setup-token 命令 claude setup-token ``` **使用第三方 API 代理**：如果你使用非官方 API 端点（如自建代理或兼容服务），需要额外配置： ```json // ~/.claude/settings.json { "env": { "ANTHROPIC_AUTH_TOKEN": "your-token", "ANTHROPIC_BASE_URL": "https://your-proxy.example.com/api/anthropic" } } ``` > **注意**：`settings.json` 中包含敏感信息，确保不要提交到 Git 仓库。在 `.gitignore` 中添加 `.claude/`。 ### 3.2 首次启动 进入你的项目目录，启动 Claude Code： ```bash # 进入一个空目录作为练习 mkdir ~/my-first-project && cd ~/my-first-project # 启动 Claude Code claude ``` 首次启动时，你会看到 Claude Code 的交互界面： ``` ╭──────────────────────────────────────────────╮ │ Claude Code 2.1.56 │ │ │ │ Working directory: ~/my-first-project │ │ Model: claude-sonnet-4-6 │ ╰──────────────────────────────────────────────╯ > ``` 在 `>` 提示符后直接输入你的指令即可。 ### 3.3 常用启动参数 ```bash # 指定模型（opus 最强，sonnet 平衡，haiku 快速） claude --model opus # 继续上一次对话 claude --continue # 恢复指定会话 claude --resume # 非交互模式（适合脚本和管道） claude -p "解释当前目录的项目结构" # 限制最大花费（配合 -p 使用） claude -p "修复测试" --max-budget-usd 1.0 # 创建 git worktree 隔离工作 claude --worktree my-feature ``` --- ## 四、核心配置：CLAUDE.md `CLAUDE.md` 是 Claude Code 的**项目级指令文件**，相当于给 AI 助手一份"工作手册"。Claude Code 启动时会自动读取该文件，并遵循其中的规则。 ### 4.1 配置层级 Claude Code 的配置有多个层级，优先级从高到低：  > *图表 2* | 文件位置 | 作用域 | 典型内容 | |----------|--------|----------| | `~/.claude/CLAUDE.md` | 全局（所有项目） | 个人偏好：语言、风格、通用规则 | | `项目根/CLAUDE.md` | 当前项目 | 项目架构、技术栈、编码规范 | | `子目录/CLAUDE.md` | 该目录及子目录 | 模块级特殊规则 | | `~/.claude/settings.json` | 全局设置 | API 配置、插件、环境变量 | ### 4.2 创建你的第一个 CLAUDE.md ```bash # 在项目根目录创建 cat > CLAUDE.md << 'EOF' # 项目说明 这是一个学习项目，用于练习 Claude Code 的基本操作。 ## 技术栈 - 语言：Python 3.12 - 框架：Flask - 前端：HTML + Tailwind CSS ## 编码规范 - 使用中文注释 - 函数和变量名使用英文 - 遵循 PEP 8 风格 ## 工作流规则 - 修改代码后自动运行测试 - 不要自动 git commit，需手动确认 - 不要创建 .md 文档文件，除非明确要求 EOF ``` ### 4.3 全局 CLAUDE.md 示例 ```markdown # 全局偏好 ## 语言 - 默认使用中文回复 - 代码注释可用英文 ## 通用规则 - 不要自动 commit - 始终先读取文件再编辑 - 优先编辑现有文件而非创建新文件 - 不要提交敏感文件（.env、credentials） ``` 把这段内容保存到 `~/.claude/CLAUDE.md`，它会在**所有项目**中生效。 --- ## 五、权限与安全 Claude Code 执行操作前会请求你的许可。理解权限系统是安全使用的关键。 ### 5.1 四种权限模式 | 模式 | 说明 | 适用场景 | |------|------|----------| | `default` | 每次危险操作都询问 | 日常开发（推荐） | | `plan` | 只做规划，不执行任何修改 | 代码审查、架构设计 | | `acceptEdits` | 自动允许文件编辑，命令仍需确认 | 信任代码修改场景 | | `bypassPermissions` | 跳过所有权限检查 | CI/CD、沙盒环境 | ```bash # 启动时指定权限模式 claude --permission-mode plan # 非交互模式跳过权限（仅限受控环境） claude -p "运行测试" --dangerously-skip-permissions ``` ### 5.2 工具级权限控制 你可以精细控制允许或禁止哪些工具： ```bash # 只允许读取和编辑，禁止执行命令 claude --allowedTools "Read,Edit" # 禁止 Git 操作 claude --disallowedTools "Bash(git:*)" ``` ### 5.3 权限决策流程  > *图表 3* --- ## 六、基础操作实战 ### 6.1 交互式对话 启动 `claude` 后，你可以自由对话。以下是一些典型操作： ``` > 创建一个 Flask 应用的骨架 > 给 app.py 添加一个 /api/hello 的路由 > 运行 python app.py 看看能不能启动 > 帮我写一个简单的测试文件 ``` ### 6.2 斜杠命令 在交互模式中，使用 `/` 开头的命令可以触发特殊功能： | 命令 | 功能 | |------|------| | `/help` | 显示帮助信息 | | `/clear` | 清空当前对话上下文 | | `/compact` | 压缩上下文（长对话时节省 token） | | `/cost` | 显示当前会话的 API 调用费用 | | `/model` | 切换模型 | | `/permissions` | 查看和修改权限设置 | | `/mcp` | 管理 MCP 服务器 | ### 6.3 非交互模式（-p） `-p` 模式非常适合脚本集成和自动化场景： ```bash # 快速代码审查 claude -p "审查 src/main.py 的代码质量，指出潜在问题" # 生成提交信息 claude -p "根据当前 git diff 生成一个规范的 commit message" # 批量重命名 claude -p "把所有 .js 文件中的 getUserName 改为 fetchUserName" # 搭配管道使用 cat error.log | claude -p "分析这段错误日志的根因" ``` ### 6.4 会话管理  > *图表 4* --- ## 七、实战案例：构建待办事项 Web 应用 现在让我们用 Claude Code 从零开始构建一个完整的待办事项应用。整个过程不需要手动编写任何代码。 ### 7.1 项目初始化 ```bash # 创建项目目录 mkdir ~/todo-app && cd ~/todo-app # 初始化 Git（推荐，Claude Code 能更好地管理变更） git init # 创建 CLAUDE.md cat > CLAUDE.md << 'EOF' # 待办事项应用 ## 技术栈 - 后端：Python Flask - 前端：HTML + Tailwind CSS（CDN） - 数据存储：SQLite ## 要求 - 使用中文界面 - 简洁现代的 UI 设计 - 支持增删改查操作 - 代码遵循 PEP 8 EOF # 启动 Claude Code claude ``` ### 7.2 让 Claude Code 构建应用 在 Claude Code 交互界面中输入： ``` > 根据项目要求，创建一个完整的 Flask 待办事项应用。 > 要求： > 1. app.py 作为主程序 > 2. 使用 SQLite 存储 > 3. HTML 模板放在 templates/ 目录 > 4. 使用 Tailwind CSS CDN > 5. 支持添加、完成、删除待办事项 > 6. 界面要美观，中文显示 ``` Claude Code 会： 1. 创建 `app.py`（Flask 主程序） 2. 创建 `templates/index.html`（页面模板） 3. 安装 Flask 依赖 4. 初始化数据库 ### 7.3 运行和调试 ``` > 运行应用，看看有没有报错 ``` Claude Code 会执行 `python app.py`，然后报告结果。如果有错误，它会自动尝试修复。 ``` > 打开浏览器看看效果。给首页添加一个"清空已完成"的按钮 ``` Claude Code 会修改模板文件，添加新功能。 ### 7.4 预期项目结构 ``` todo-app/ ├── CLAUDE.md # 项目指令 ├── app.py # Flask 主程序 ├── requirements.txt # Python 依赖 ├── templates/ │ └── index.html # 主页面模板 ├── static/ # 静态资源（可选） └── .gitignore # Git 忽略规则 ``` ### 7.5 测试 ``` > 给这个应用写单元测试，使用 pytest ``` Claude Code 会创建 `tests/` 目录并编写测试文件，然后运行测试。 ``` > 运行所有测试，确保通过 ``` ### 7.6 部署 ``` > 把这个应用部署到本地，使用 gunicorn 作为生产服务器 ``` --- ## 八、Settings 配置详解 `~/.claude/settings.json` 是 Claude Code 的核心配置文件。 ### 8.1 完整配置示例 ```json { "env": { "ANTHROPIC_API_KEY": "sk-ant-xxxxx", "API_TIMEOUT_MS": "300000" }, "permissions": { "allow": [ "Bash(python:*)", "Bash(npm:*)", "Bash(git status:*)", "Read", "Edit" ], "deny": [ "Bash(rm -rf:*)" ] }, "theme": "dark", "enabledPlugins": { "superpowers@claude-plugins-official": true, "context7@claude-plugins-official": true } } ``` ### 8.2 关键配置项说明 | 配置路径 | 说明 | 示例 | |----------|------|------| | `env` | 环境变量注入 | API 密钥、超时设置 | | `permissions.allow` | 自动允许的操作白名单 | `"Bash(python:*)"` 允许所有 python 命令 | | `permissions.deny` | 禁止的操作黑名单 | `"Bash(rm -rf:*)"` 禁止危险删除 | | `theme` | 界面主题 | `"dark"` 或 `"light"` | | `enabledPlugins` | 启用的插件列表 | 插件名和开关 | --- ## 九、MCP 服务器入门 MCP（Model Context Protocol）是 Claude Code 的扩展机制，允许连接外部工具和服务。 ### 9.1 添加 MCP 服务器 ```bash # 添加一个 HTTP 类型的 MCP 服务器 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp # 添加一个 stdio 类型的本地服务器 claude mcp add my-tools -- npx my-mcp-server # 查看已配置的服务器 claude mcp list # 移除服务器 claude mcp remove sentry ``` ### 9.2 常用 MCP 服务器推荐 | 服务器 | 功能 | 添加命令 | |--------|------|----------| | Context7 | 查询最新库文档 | 通过插件安装 | | Playwright | 浏览器自动化 | 通过插件安装 | | Sentry | 错误监控集成 | `claude mcp add --transport http sentry https://mcp.sentry.dev/mcp` | | Figma | 设计稿读取 | 通过插件安装 | ### 9.3 项目级 MCP 配置 你可以在项目根目录创建 `.mcp.json` 文件，让团队成员共享 MCP 配置： ```json { "mcpServers": { "my-api": { "type": "http", "url": "https://my-api.example.com/mcp", "headers": { "Authorization": "Bearer ${API_TOKEN}" } } } } ``` > **注意**：`.mcp.json` 可能包含敏感信息，确保加入 `.gitignore` 或使用环境变量。 --- ## 十、常见问题与排查 ### 10.1 安装问题 | 问题 | 解决方案 | |------|----------| | `npm install -g` 权限报错 | 使用 nvm 安装 Node.js，或修改 npm prefix | | `command not found: claude` | 检查 npm 全局路径是否在 `$PATH` 中 | | Node.js 版本过低 | 确保 `node -v` >= 18.0.0 | | 安装卡住/超时 | 检查网络代理设置，或使用镜像源 | ### 10.2 认证问题 | 问题 | 解决方案 | |------|----------| | `claude auth` 无法打开浏览器 | 手动访问终端中显示的 URL | | API Key 无效 | 检查 Key 是否以 `sk-ant-` 开头，是否过期 | | 第三方代理连接失败 | 检查 `ANTHROPIC_BASE_URL` 配置是否正确 | ### 10.3 运行时问题 | 问题 | 解决方案 | |------|----------| | 上下文过长被截断 | 使用 `/compact` 压缩对话历史 | | 响应变慢 | 切换到更快的模型：`/model` → haiku | | 权限弹窗太频繁 | 配置 `settings.json` 中的 `permissions.allow` | | 误操作需要撤销 | `git diff` 查看变更，`git checkout -- .` 撤销 | ### 10.4 健康检查 ```bash # Claude Code 内置诊断工具 claude doctor # 检查版本和更新 claude --version claude update ``` --- ## 十一、工作流全景图  > *图表 5* --- ## 十二、命令速查表 | 命令 | 说明 | |------|------| | `claude` | 启动交互式会话 | | `claude -p "指令"` | 非交互模式，输出后退出 | | `claude --continue` | 继续上次对话 | | `claude --resume` | 选择历史会话恢复 | | `claude --model opus` | 指定使用 Opus 模型 | | `claude --worktree` | 在隔离的 git worktree 中工作 | | `claude auth` | 管理认证 | | `claude mcp list` | 列出 MCP 服务器 | | `claude doctor` | 运行诊断 | | `claude update` | 更新到最新版本 | | `/compact` | 压缩上下文 | | `/cost` | 查看费用 | | `/help` | 查看帮助 | --- ## 延伸阅读 - [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code/overview) - [Claude Code 快速入门](https://code.claude.com/docs/en/quickstart) - [Anthropic 官方博客](https://www.anthropic.com/blog) - [Claude Code GitHub](https://github.com/anthropics/claude-code) - [Claude Code 配置完整指南](https://www.productbuilder.net/learn/claude-code-settings) - [Claude Code 权限指南](https://www.claudedirectory.org/blog/claude-code-permissions-guide) --- **训练营适用性评估**： | 训练营类型 | 适用性 | 预计教学时长 | |-----------|--------|-------------| | AI 编程工具入门营 | 高度适合 | 2-3 小时（含实操） | | 全栈开发训练营 | 适合（作为工具环节） | 1-2 小时 | | DevOps 自动化营 | 适合（侧重 CLI 和自动化） | 1.5 小时 | | 企业内训（技术团队） | 高度适合 | 2 小时（含企业配置） | 前置要求：学员需具备基本终端操作能力（cd、ls、git 基础），有 Python 或 JavaScript 编程经验更佳。建议每人配备独立开发环境，确保网络可访问 Anthropic API。 > [!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 等场景全覆盖。