Appearance
很多人在部署Claude Code时会遇到这些问题：命令行黑屏报错、环境变量配置不生效、API连接失败、VSCode插件无法启动……这篇教程的目标是让你在30分钟内完成从零到可用的全流程部署。
Claude Code到底是什么
很多人把它当成"会写代码的ChatGPT"，这个理解并不完全准确。
Claude Code是Anthropic推出的AI编程代理，它不仅能理解需求、生成代码，更重要的是能够直接操作项目文件——创建、修改、删除、运行测试、查看日志。
核心能力：
| 能力 | 说明 |
|---|---|
| 项目理解 | 自动分析项目结构、依赖关系、代码逻辑 |
| 代码生成 | 根据自然语言描述生成完整功能模块 |
| 智能重构 | 识别代码异味并提供优化方案 |
| Bug诊断 | 分析错误日志、定位问题根源、提供修复建议 |
| 多语言支持 | Python、JavaScript、TypeScript、Java、Go等 |
环境准备
系统要求
Windows用户：
- Windows 10版本1809或更高（推荐Windows 11）
- 64位操作系统
- 至少8GB内存（推荐16GB）
必备软件
1. Node.js环境（必需）
Claude Code基于Node.js运行，需要Node.js 18+。
安装步骤：
- 访问Node.js官网，下载LTS（长期支持）版本
- 安装时勾选"自动添加到PATH"
验证安装：
bash
node --version # 应显示 v20.x.x 或更高
npm --version # 应显示 10.x.x 或更高国内用户建议配置npm镜像源：
bash
npm config set registry https://registry.npmmirror.com2. Git工具（Windows必需）
Claude Code依赖Git for Windows提供的Unix风格命令行工具。
安装时选择：
- 勾选"Git Bash Here"（右键菜单集成）
- 选择"Use Git from Git Bash only"
- 换行符转换选择"Checkout as-is, commit Unix-style"
三种安装方式
方式一：npm全局安装（推荐新手）
bash
npm install -g @anthropic-ai/claude-code
# 验证
claude --version方式二：WinGet安装（Windows推荐）
bash
winget install anthropic.claude-code优势：自动处理依赖关系、集成到系统更新机制、卸载更干净。
方式三：Homebrew安装（macOS推荐）
bash
brew install claude-codeAPI配置：让Claude Code真正"活"起来
创建配置文件
步骤1：创建配置目录
bash
# Windows
mkdir %USERPROFILE%\.claude
# macOS/Linux
mkdir -p ~/.claude步骤2：创建settings.json
json
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "你的API密钥",
"ANTHROPIC_BASE_URL": "API服务地址",
"ANTHROPIC_MODEL": "模型名称",
"API_TIMEOUT_MS": "300000"
}
}参数说明
| 参数 | 说明 |
|---|---|
| ANTHROPIC_AUTH_TOKEN | API密钥，格式通常为sk-xxxxx |
| ANTHROPIC_BASE_URL | API端点地址（国内用户必填） |
| ANTHROPIC_MODEL | 默认模型，如claude-sonnet-4-6 |
| API_TIMEOUT_MS | 超时时间（毫秒），默认5分钟 |
国内用户：如何获取可用API
由于网络限制，国内用户无法直接访问Anthropic官方API。主流解决方案：
方案一：使用国内API中转服务
推荐平台：
- 阿里云百炼（提供Coding Plan套餐）
- 其他第三方中转服务
方案二：使用国产大模型替代
部分国产模型支持Anthropic API兼容接口，如阿里云千问系列。配置方式相同，只需替换Base URL和模型名称。
验证配置
配置完成后重启终端，执行：
bash
claude如果配置正确，会看到欢迎界面：
Version: 0.1.52
API provider: Custom
Model: claude-sonnet-4-6VSCode集成
安装官方插件
- 打开VSCode，点击左侧扩展图标（或按
Ctrl+Shift+X） - 搜索"Claude Code"
- 找到Anthropic官方插件，点击安装
- 重启VSCode
插件配置
安装后，插件会自动读取~/.claude/settings.json配置。
如需单独配置，按Ctrl+,打开设置，搜索"Claude Code"，填写API Key、Base URL、默认模型。
三种使用方式
方式1：侧边栏对话
点击右上角Claude Code图标，打开对话面板。
方式2：选中代码快速操作
选中代码，按Alt+C（Windows）或Option+C（macOS）直接提问。
方式3：使用斜杠命令
/model：切换模型/clear：清空对话历史/usage：查看Token使用量/config：打开设置
常见问题排查
问题1：命令未找到
症状：输入claude提示命令不存在
解决方案：
bash
# 查看npm全局安装路径
npm config get prefix
# 将该路径添加到系统PATH
# Windows: 系统属性 → 环境变量 → Path → 新建
# macOS/Linux: 编辑 ~/.bashrc 或 ~/.zshrc
export PATH="$PATH:$(npm config get prefix)/bin"问题2：API连接失败
排查步骤：
bash
# 运行自诊断命令
claude /doctor这个命令会自动检测配置问题并给出建议。
问题3：Token消耗过快
优化策略：
- 创建
.claudeignore文件排除无关文件：
bash
node_modules/
dist/
build/
*.log
.env
coverage/
*.min.js使用精准引用而非全项目扫描
定期清空对话历史：
bash
/clear问题4：Windows下Git Bash路径错误
解决方案：
powershell
# PowerShell
$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"实战案例
5分钟生成待办事项应用
需求描述：
创建一个待办事项Web应用，要求：
1. 使用纯HTML + CSS + JavaScript，无需框架
2. 支持添加、删除、标记完成任务
3. 数据保存在localStorage，刷新不丢失
4. 界面简洁美观，支持深色模式
5. 添加任务统计功能（总数、已完成、未完成）Claude Code的工作流程：理解需求→创建文件→编写代码→测试验证，整个过程约2-3分钟。
进阶技巧
使用@符号精准引用文件
解释 @src/auth.js 的登录逻辑使用!符号执行命令并注入结果
! git diff --stat
分析这次改动是否有遗漏创建项目说明文件CLAUDE.md
在项目根目录创建CLAUDE.md，写入项目规范、技术栈、注意事项。Claude Code会自动读取这个文件。
成本控制
选择合适的模型
| 模型 | 特点 | 适用场景 |
|---|---|---|
| claude-haiku | 最便宜 | 简单任务 |
| claude-sonnet | 性价比最高 | 日常开发 |
| claude-opus | 最强大 | 复杂重构 |
根据任务难度切换模型：
/model claude-haiku-4-5安全注意事项
- 不要泄露敏感信息：确保
.env文件已添加到.claudeignore - 审查生成的代码：AI生成的代码可能存在安全漏洞
- 使用企业版API时确认数据隐私政策
总结
Claude Code确实能让开发效率提升3-5倍——不是因为它写代码有多快，而是因为它能帮你专注于真正重要的决策，把
