Claude Code 超详细完整指南（2025最新版）

🚀 终端AI编程助手 | 高频使用点 + 生态工具 + 完整命令参考 + 最新MCP配置

📋 目录

• 🎯 快速开始（5分钟上手）
• 📦 详细安装指南
• 系统要求
• Windows安装（WSL方案）
• macOS安装
• Linux安装
• 安装验证
• 🔧 配置与认证
• 首次认证
• 环境变量配置
• 代理配置
• ⚡ 基础命令详解
• 启动命令
• 会话管理
• 文件操作
• 🧠 Think模式完全指南
• 🔌 MCP服务器配置详解
• MCP基础概念
• 添加MCP服务器
• 10个必备MCP服务器
• MCP故障排除
• 💾 记忆系统详解
• 🎮 高级使用技巧
• 💰 成本控制策略
• 📱 移动端使用方案
• 🛠️ 故障排除指南
• 📚 完整命令参考
• 🔗 生态工具与资源

___

🎯 快速开始（5分钟上手）

最快安装方式

# 1. 确保Node.js已安装（v18+） node --version # 2. 安装Claude Code npm install -g @anthropic-ai/claude-code # 3. 验证安装 claude --version # 4. 启动并认证 claude

立即体验

# 快速执行任务 claude -p "创建一个Python快速排序函数" # 跳过权限确认（提高效率） claude --dangerously-skip-permissions # 继续上次对话 claude --continue

___

📦 详细安装指南

系统要求

Windows安装（WSL方案）

为什么需要WSL？
Claude Code基于Unix哲学设计，需要POSIX兼容环境。WSL提供了最佳的Windows兼容性。

步骤1：安装WSL

# 在PowerShell（管理员模式）中运行 wsl --install # 查看可用发行版 wsl --list --online # 安装特定发行版（推荐Ubuntu） wsl --install -d Ubuntu

步骤2：配置WSL环境

# 重启后，在WSL终端中更新系统 sudo apt update && sudo apt upgrade -y # 安装必要工具 sudo apt install -y curl wget git build-essential

步骤3：安装Node.js

# 使用NodeSource仓库（推荐） curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 验证安装 node --version npm --version

步骤4：安装Claude Code

# 全局安装 npm install -g @anthropic-ai/claude-code # 验证安装 claude --version

macOS安装

方法1：使用Homebrew（推荐）

# 安装Homebrew（如果未安装） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 安装Node.js brew install node@20 # 安装Claude Code npm install -g @anthropic-ai/claude-code

方法2：直接安装

# 下载并安装Node.js # 访问 https://nodejs.org 下载macOS安装包 # 安装Claude Code npm install -g @anthropic-ai/claude-code

Linux安装

Ubuntu/Debian系统

# 更新包列表 sudo apt update # 安装Node.js curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 安装Claude Code npm install -g @anthropic-ai/claude-code

CentOS/RHEL/Fedora系统

# 安装Node.js curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - sudo yum install nodejs # 或者在Fedora上 sudo dnf install nodejs # 安装Claude Code npm install -g @anthropic-ai/claude-code

Arch Linux

# 安装Node.js sudo pacman -S nodejs npm # 安装Claude Code npm install -g @anthropic-ai/claude-code

安装验证

# 检查版本 claude --version # 输出：Claude Code v1.0.0 # 检查帮助 claude --help # 测试基本功能 claude -p "echo 'Hello Claude Code'"

___

🔧 配置与认证

首次认证

自动认证流程

# 启动Claude Code claude # 系统提示： # Welcome to Claude Code! # To get started, you need to authenticate with your Anthropic account. # Press Enter to open your browser and complete authentication...

手动认证（如果自动认证失败）

# 手动初始化 claude init # 如果浏览器无法自动打开 claude auth login --manual

认证成功标志

✓ Authentication successful!
✓ Claude Code is ready to use.

环境变量配置

基础配置

# 设置API密钥（如果需要） export ANTHROPIC_API_KEY=your_api_key # 设置自定义模型 export ANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # 设置基础URL（用于代理） export ANTHROPIC_BASE_URL=https://your-proxy.com/v1

持久化配置

# 添加到shell配置文件 echo 'export ANTHROPIC_API_KEY=your_api_key' >> ~/.bashrc echo 'export ANTHROPIC_MODEL=claude-3-5-sonnet-20241022' >> ~/.bashrc # 重新加载配置 source ~/.bashrc

代理配置

HTTP代理

# 设置代理 export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=http://proxy.company.com:8080 # 设置npm代理 npm config set proxy http://proxy.company.com:8080 npm config set https-proxy http://proxy.company.com:8080

国内用户优化

# 使用淘宝npm镜像 npm config set registry https://registry.npmmirror.com # 临时使用镜像安装 npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

___

⚡ 基础命令详解

启动命令

高级启动选项

# 跳过权限确认（危险但高效） claude --dangerously-skip-permissions # 指定配置文件 claude --config /path/to/config.json # 调试模式 claude --debug # 静默模式 claude --quiet # 指定工作目录 claude --cwd /path/to/project

会话管理

会话内命令（斜杠命令）

文件操作

# 分析项目结构 claude "分析这个项目的架构" # 创建文件 claude "创建一个用户认证的API" # 修改文件 claude "修复src/utils/auth.js中的bug" # 批量操作 claude "将所有.js文件转换为TypeScript"

___

🧠 Think模式完全指南

Think模式是Claude Code的核心特色，能激活AI的深度思考能力。

Think模式对比

使用示例

基础思考

用户：think 这个函数有什么问题？

深度思考

用户：think hard 设计一个高并发的用户认证系统

极深度思考

用户：ultrathink 分析这个分布式系统的性能瓶颈并提出优化方案

Think模式最佳实践

1. 根据问题复杂度选择：简单问题用think，复杂问题用ultrathink
2. 成本考虑：Max套餐用户可以多用ultrathink，免费用户谨慎使用
3. 时间权衡：紧急任务用基础模式，深度分析用高级模式

___

🔌 MCP服务器配置详解

MCP基础概念

MCP（Model Context Protocol）是Anthropic推出的开源通信标准，让Claude Code可以：

• 📁 访问本地文件系统
• 🌐 连接各种API服务
• 🗄️ 操作数据库
• 🛠️ 集成开发工具
• 🔧 自动化任务

MCP服务器作用域

添加MCP服务器

方法1：命令行添加（推荐新手）

# 基本语法 claude mcp add 名称 [选项] -- 命令 [参数...] # 添加文件系统访问 claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects # 添加GitHub集成 claude mcp add github -s user -e GITHUB_TOKEN=your_token -- npx -y @modelcontextprotocol/server-github

方法2：编辑配置文件（推荐高级用户）

{ "mcpServers": { "filesystem": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"], "env": {} }, "github": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "your_github_token" } } } }

10个必备MCP服务器

1. 文件系统访问（必装）

claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects ~/Desktop

用途：让Claude直接读写文件，修改代码

2. GitHub集成

claude mcp add github -s user -e GITHUB_TOKEN=your_token -- npx -y @modelcontextprotocol/server-github

用途：管理issues、PRs、代码审查

3. 网页浏览器控制

claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer

用途：自动化网页操作、爬虫、测试

4. 数据库连接（PostgreSQL）

claude mcp add postgres -s user -e DATABASE_URL=postgresql://user:pass@localhost/db -- npx -y @modelcontextprotocol/server-postgres

用途：直接查询和操作数据库

5. API调用工具

claude mcp add fetch -s user -- npx -y @kazuph/mcp-fetch

用途：调用各种REST API

6. 搜索引擎

claude mcp add search -s user -e BRAVE_API_KEY=your_key -- npx -y @modelcontextprotocol/server-brave-search

用途：搜索最新信息

7. Slack集成

claude mcp add slack -s user -e SLACK_TOKEN=your_token -- npx -y @modelcontextprotocol/server-slack

用途：发送消息、管理频道

8. 时间管理

claude mcp add time -s user -- npx -y @modelcontextprotocol/server-time

用途：时区转换、日期计算

9. 内存存储

claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory

用途：跨对话保存信息

10. Sequential Thinking（思维链）

claude mcp add thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking

用途：复杂问题分步骤思考

MCP管理命令

# 查看已安装的MCP服务器 claude mcp list # 删除MCP服务器 claude mcp remove server_name # 测试MCP服务器 claude mcp test server_name # 查看MCP状态 /mcp

MCP故障排除

常见错误1：工具名称验证失败

API Error 400: "tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}'"

解决方案：

• 确保服务器名称只包含字母、数字、下划线和连字符
• 名称长度不超过64个字符

常见错误2：找不到MCP服务器

MCP server 'my-server' not found

解决方案：

1. 检查作用域设置是否正确
2. 运行claude mcp list确认服务器已添加
3. 重启Claude Code

常见错误3：Windows路径问题

Error: Cannot find module 'C:UsersusernameDocuments'

解决方案：使用正斜杠或双反斜杠

# 正确方式 claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents

调试技巧

# 启用调试模式 claude --mcp-debug # 查看日志文件 tail -f ~/Library/Logs/Claude/mcp*.log # macOS type "%APPDATA%\Claude\logs\mcp*.log" # Windows # 手动测试服务器 npx -y @modelcontextprotocol/server-filesystem ~/Documents

___

💾 记忆系统详解

Claude Code的记忆系统让AI能够记住你的偏好和项目信息。

记忆文件类型

用户记忆文件模板

# 用户偏好设置 ## 编程语言偏好 - 主要语言：Python, JavaScript, TypeScript - 框架偏好：React, FastAPI, Express ## 代码风格 - 缩进：4个空格 - 变量命名：camelCase（JS）, snake_case（Python） - 函数命名：动词开头，描述性强 - 注释：中文，详细说明 ## 开发环境 - 编辑器：VS Code, Cursor - 终端：zsh with oh-my-zsh - 版本控制：Git with conventional commits ## 工作习惯 - 测试驱动开发（TDD） - 代码审查必须 - 文档先行 - 安全第一 ## 常用工具 - 包管理：npm, pip, poetry - 数据库：PostgreSQL, Redis - 部署：Docker, Kubernetes

项目记忆文件模板

# 项目配置 ## 项目信息 - 项目名称：电商平台API - 技术栈：Node.js + Express + PostgreSQL + Redis - 开发环境：Node 20.x, npm 10.x - 部署环境：Docker + Kubernetes ## 架构说明 - 采用微服务架构 - API网关：Kong - 认证：JWT + Redis session - 数据库：主从分离，读写分离 ## 编码规范 - ESLint + Prettier - 函数命名：camelCase - 文件命名：kebab-case - 提交信息：Conventional Commits ## 环境变量 - DATABASE_URL：数据库连接 - REDIS_URL：Redis连接 - JWT_SECRET：JWT密钥 - API_PORT：API端口（默认3000） ## 常用命令 - 启动开发：`npm run dev` - 运行测试：`npm test` - 构建项目：`npm run build` - 数据库迁移：`npm run migrate` - 代码检查：`npm run lint` ## API设计规范 - RESTful风格 - 统一错误处理 - 请求限流 - API版本控制（/api/v1/） ## 安全要求 - 所有API需要认证 - 敏感数据加密存储 - SQL注入防护 - XSS防护 ## 测试要求 - 单元测试覆盖率 > 80% - 集成测试必须 - E2E测试关键流程 - 性能测试 ## 部署流程 1. 代码提交到main分支 2. 自动触发CI/CD 3. 运行所有测试 4. 构建Docker镜像 5. 部署到Kubernetes 6. 健康检查 ## 注意事项 - 数据库操作必须使用事务 - 异步操作要有错误处理 - 日志记录要详细 - 监控告警要及时

记忆文件管理

# 编辑用户记忆 /edit # 编辑项目记忆（在项目目录中） /edit project # 查看当前记忆内容 claude "显示我的偏好设置" # 更新记忆内容 claude "记住我喜欢使用TypeScript而不是JavaScript"

___

🎮 高级使用技巧

1. 项目架构分析

# 分析整个项目 claude "分析这个项目的架构，给出改进建议" # 分析特定目录 claude "分析src/components目录的组件设计" # 生成架构图 claude "为这个项目生成Mermaid架构图"

2. 代码重构

# 重构为设计模式 claude "将这个类重构为单例模式" # 性能优化 claude "优化这个函数的性能，减少时间复杂度" # 代码清理 claude "清理这个文件中的重复代码"

3. 自动化测试

# 生成单元测试 claude "为src/utils/auth.js生成完整的单元测试" # 生成集成测试 claude "为用户注册API生成集成测试" # 测试覆盖率分析 claude "分析测试覆盖率，找出未测试的代码"

4. 文档生成

# 生成API文档 claude "为所有API端点生成OpenAPI 3.0文档" # 生成README claude "为这个项目生成详细的README.md" # 生成代码注释 claude "为所有公共函数添加JSDoc注释"

5. Git工作流

# 智能提交 claude "分析代码变更，生成合适的commit message" # 代码审查 claude "审查这个PR的代码变更" # 分支管理 claude "创建feature分支并实现用户登录功能"

6. 数据库操作

# 设计数据库 claude "为电商系统设计数据库表结构" # 生成迁移文件 claude "生成用户表的数据库迁移文件" # 查询优化 claude "优化这个SQL查询的性能"

7. 部署自动化

# 生成Dockerfile claude "为这个Node.js项目生成优化的Dockerfile" # Kubernetes配置 claude "生成Kubernetes部署配置文件" # CI/CD流水线 claude "创建GitHub Actions工作流"

8. 错误调试

# 日志分析 tail -f app.log | claude -p "分析错误日志，找出问题根源" # 性能分析 claude "分析这个性能报告，找出瓶颈" # 内存泄漏检测 claude "检查这个代码是否有内存泄漏"

9. 安全审计

# 安全扫描 claude "扫描这个项目的安全漏洞" # 依赖检查 claude "检查package.json中的安全漏洞" # 代码安全 claude "审查这个代码的安全性"

10. 多语言支持

# 国际化 claude "为这个React应用添加i18n支持" # 翻译 claude "将这些英文注释翻译成中文" # 本地化 claude "为中国用户优化这个应用"

___

💰 成本控制策略

Token使用优化

1. 使用/compact命令

# 定期压缩对话 /compact # 自动压缩（推荐） claude --auto-compact

2. 限定操作范围

# 指定具体文件 claude "修复src/auth.js中的bug" # 而不是 claude "修复认证相关的bug"

3. 使用.claudeignore

# 创建.claudeignore文件 echo "node_modules/" >> .claudeignore echo "dist/" >> .claudeignore echo "*.log" >> .claudeignore echo ".env" >> .claudeignore

Think模式成本控制

成本监控

# 查看使用统计 claude stats # 查看当前对话Token数 claude token-count # 设置使用限制 claude set-limit --daily 1000

___

📱 移动端使用方案

Android方案（Termux）

安装Termux

1. 从F-Droid下载Termux（推荐）
2. 或从Google Play下载

配置环境

# 更新包列表 pkg update && pkg upgrade # 安装必要工具 pkg install nodejs git openssh # 安装Claude Code npm install -g @anthropic-ai/claude-code # 配置存储权限 termux-setup-storage

优化配置

# 安装oh-my-zsh pkg install zsh sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" # 配置快捷键 mkdir ~/.termux echo "extra-keys = [['ESC','/','-','HOME','UP','END','PGUP'],['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN']]" > ~/.termux/termux.properties

iOS方案（SSH）

使用iSH App

# 安装Node.js apk add nodejs npm # 安装Claude Code npm install -g @anthropic-ai/claude-code

使用SSH连接

# 连接到远程服务器 ssh user@your-server.com # 在服务器上使用Claude Code claude

移动端优化技巧

1. 使用简短命令：移动端输入不便，多用缩写
2. 语音输入：利用手机语音转文字功能
3. 云端同步：使用云服务器保持会话连续性
4. 离线准备：提前下载必要的MCP服务器

___

🛠️ 故障排除指南

安装问题

问题1：command not found: claude

# 检查PATH echo $PATH # 查看npm全局路径 npm config get prefix # 添加到PATH echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc source ~/.bashrc

问题2：权限错误

# 设置npm全局目录 mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile source ~/.profile

问题3：网络连接问题

# 检查网络 ping anthropic.com # 设置代理 export HTTP_PROXY=http://proxy:port export HTTPS_PROXY=http://proxy:port # 使用镜像源 npm config set registry https://registry.npmmirror.com

认证问题

问题1：认证失败

# 清除认证信息 claude logout # 重新认证 claude init # 手动认证 claude auth login --manual

问题2：API密钥问题

# 检查环境变量 echo $ANTHROPIC_API_KEY # 重新设置 export ANTHROPIC_API_KEY=your_new_key

性能问题

问题1：响应慢

# 清理缓存 claude cache clear # 压缩对话 /compact # 限定范围 claude "只分析src目录"

问题2：内存占用高

# 重启Claude Code claude restart # 清理日志 claude logs clear

MCP问题

问题1：MCP服务器无法启动

# 检查服务器状态 claude mcp test server_name # 查看错误日志 claude mcp logs server_name # 重新安装服务器 claude mcp remove server_name claude mcp add server_name ...

问题2：工具不可用

# 检查MCP列表 claude mcp list # 重启MCP服务 claude mcp restart # 检查权限 ls -la ~/.claude.json

___

📚 完整命令参考

基础命令

高级选项

# 跳过权限确认 claude --dangerously-skip-permissions # 指定配置文件 claude --config /path/to/config.json # 调试模式 claude --debug # 静默模式 claude --quiet # 指定工作目录 claude --cwd /path/to/project # 自动压缩 claude --auto-compact # MCP调试 claude --mcp-debug

会话内命令

MCP管理命令

# 添加MCP服务器 claude mcp add name [options] -- command [args...] # 删除MCP服务器 claude mcp remove name # 列出MCP服务器 claude mcp list # 测试MCP服务器 claude mcp test name # 查看MCP日志 claude mcp logs name # 重启MCP服务 claude mcp restart [name]

认证命令

# 初始化认证 claude init # 登录 claude auth login # 登出 claude auth logout # 查看认证状态 claude auth status # 刷新token claude auth refresh

配置命令

# 查看配置 claude config show # 设置配置 claude config set key value # 重置配置 claude config reset # 导出配置 claude config export > config.json # 导入配置 claude config import config.json

缓存管理

# 清理缓存 claude cache clear # 查看缓存大小 claude cache size # 缓存统计 claude cache stats

日志管理

# 查看日志 claude logs show # 清理日志 claude logs clear # 日志级别 claude logs level debug|info|warn|error

___

🔗 生态工具与资源

官方资源

• Claude Code官方文档
• MCP官方文档
• GitHub仓库
• 社区讨论

第三方工具

1. Claude Code Router

• 项目地址：https://github.com/LLM-Red-Team/kimi-cc
• 功能：多模型路由，成本优化
• 安装：npm install -g claude-code-router

2. Kimi K2集成

• 项目地址：https://github.com/fakerybakery/claude-code-kimi-groq
• 功能：集成Kimi和Groq模型
• 配置：环境变量设置

3. VS Code扩展

• 扩展名：Claude Code Integration
• 功能：在VS Code中使用Claude Code
• 安装：VS Code扩展市场搜索

4. Cursor集成

• 功能：在Cursor中使用Claude Code
• 配置：Terminal集成

MCP服务器生态

官方服务器

• @modelcontextprotocol/server-filesystem
• @modelcontextprotocol/server-github
• @modelcontextprotocol/server-postgres
• @modelcontextprotocol/server-brave-search

社区服务器

• @kazuph/mcp-fetch
• @modelcontextprotocol/server-puppeteer
• @modelcontextprotocol/server-slack
• @modelcontextprotocol/server-memory

中文资源

• MCP服务器列表（中文）
• Claude Code中文社区

API中转服务

推荐服务商

1. LaoZhang.AI

• 网址：https://api.laozhang.ai
• 特点：成本降低70%，中国优化
• 支持：Claude、GPT、Gemini等

1. 其他服务商

• OpenRouter：多模型支持
• Together AI：开源模型
• Groq：高速推理

学习资源

视频教程

• Claude Code入门教程
• MCP配置详解

博客文章

• Claude Code最佳实践
• MCP开发指南

书籍推荐

• 《AI辅助编程实战》
• 《终端工具大全》

___

🎯 总结与建议

立即行动清单

1. ✅ 安装Claude Code

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

1. ✅ 完成认证

claude init

1. ✅ 添加基础MCP服务器

claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

1. ✅ 配置记忆文件

/edit

1. ✅ 体验Think模式

think 创建一个React组件

最佳实践总结

1. 效率优化

• 使用--dangerously-skip-permissions跳过权限确认
• 定期使用/compact压缩对话
• 配置详细的记忆文件
• 合理使用Think模式

1. 成本控制

• 限定操作范围
• 使用.claudeignore排除无关文件
• 选择合适的Think模式
• 考虑API中转服务

1. 安全建议

• 保护API密钥
• 谨慎使用权限跳过
• 定期备份配置
• 只安装可信的MCP服务器

1. 团队协作

• 使用项目级MCP配置
• 统一编码规范
• 共享记忆文件模板
• 建立使用规范

未来发展

Claude Code正在快速发展，预期功能：

• 2025 Q1：正式版发布，性能优化
• 2025 Q2：团队协作功能，VS Code集成
• 2025 Q3：企业版，私有化部署
• 2025 Q4：AI代理链，多模态支持

获取帮助

遇到问题时的求助渠道：

1. 查看本指南的故障排除部分
2. 访问官方文档和GitHub Issues
3. 加入社区讨论
4. 联系技术支持

___

🎉 恭喜！您已经掌握了Claude Code的完整使用方法。现在开始您的AI辅助编程之旅吧！

适用版本：Claude Code v1.0.0+