Claude Code 安装配置与实战使用指南

注意 -g 参数让命令全局可用，Windows 下 --scripts-prepend-node-path 是为了确保脚本能正确找到 Node.js 路径。

若提示 "claude 不是可运行命令"，请检查 npm 全局路径 (npm prefix -g) 并将其添加到系统环境变量 PATH 中，然后重启终端。

3.3 macOS 系统安装

方式一：官方一键脚本

curl -fsSL https://claude.ai/install.sh | bash

方式二：npm 安装

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

如需配置环境变量，可将路径加入 shell 配置：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3.4 Linux 系统安装

Ubuntu/Debian 用户可直接运行：

curl -fsSL https://claude.ai/install.sh | bash
# 或使用 npm
sudo npm install -g @anthropic-ai/claude-code

3.5 初始化配置

首次运行 claude 会引导配置 API Key。按提示完成即可开始使用。

四、配置与优化

4.1 配置文件位置

配置文件位于用户目录下的隐藏文件夹：

• macOS/Linux: ~/.claude/
• Windows: C:\Users\YourName\.claude

关键文件包括 settings.json（核心配置）和 .claude.json（会话配置）。

4.2 跳过新手引导

为了直接进入工作状态，可以编辑或创建 ~/.claude.json 文件：

{
  "hasCompletedOnboarding": true
}

注意 hasCompletedOnboarding 必须是顶层字段。

4.3 接入国产大模型（免翻墙方案）

国内用户可通过兼容 API 接入国产模型，避免网络限制。

阿里云百炼 Coding Plan 编辑 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_BASE_URL": "https://coding.dashscope.aliyuncs.com/apps/anthropic",
    "ANTHROPIC_MODEL": "qwen3.5-plus"
  }
}

智谱 AI

{
  "env": {
    "ANTHROPIC_API_KEY": "YOUR_API_KEY",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5"
  }
}

这里 glm-4.5-air 适合轻量级快速响应，glm-4.7 性能均衡，glm-5 则处理复杂任务。

4.4 代理配置

如需访问官方服务且需要代理：

# macOS/Linux
export HTTPS_PROXY="http://127.0.0.1:7897"
export HTTP_PROXY="http://127.0.0.1:7897"

# 永久生效
printf '%s\n' 'export HTTPS_PROXY="http://127.0.0.1:7897"' 'export HTTP_PROXY="http://127.0.0.1:7897"' >> ~/.zshrc
source ~/.zshrc

五、核心命令与使用技巧

5.1 基础命令速查

5.2 实用场景示例

代码审查

claude -f main.py "帮我审查这段代码，找出潜在问题"

代码重构

claude -f old_code.js "帮我重构这段代码，提高可读性"

单元测试生成

claude -f utils.py "为这个模块生成完整的单元测试"

5.3 交互式工作流

进入项目目录后启动：

cd /path/to/your/project
claude

典型对话流程如下：

帮我创建一个 Python Flask 项目框架

好的，我将为你创建以下结构：app.py, requirements.txt, templates/, static/。是否需要我立即创建这些文件？

是的，请创建

✓ 已创建 app.py ... 接下来需要我为 app.py 添加基础路由吗？

这种多轮对话能让我们像结对编程一样高效完成任务。

六、高级用法与最佳实践

6.1 项目管理策略

首次进入项目目录时，Claude Code 会询问是否信任该目录（Do you trust this directory?）。选择 Y 后，它才能读写文件。

推荐工作流：

1. 初始化：让 Claude 分析现有代码结构
2. 任务分解：将大任务拆分为小步骤
3. 增量开发：逐步实现功能，每步验证
4. 代码审查：定期让 Claude 审查代码质量

6.2 MCP 配置

MCP（Model Context Protocol）允许 Claude Code 访问外部工具和数据源。例如配置文件系统或 Git 服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    }
  }
}

6.3 Team Mode 实验性功能

2026 年新增的 Team Mode 支持多 Agent 协作，可在配置中启用：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

启用后可分配子任务给专用 Agent，并行处理多个开发任务。

6.4 性能优化技巧

• 限制上下文长度：claude --max-tokens 4096 "简短回答这个问题"
• 使用缓存：claude --cache-enabled
• 批量处理文件：claude -f src/*.py "统一格式化这些文件"

七、常见问题与解决方案

Q1: 提示 'claude 命令不存在' 检查 npm 全局路径 (npm prefix -g) 并添加到系统 PATH，重启终端。

Q2: Node.js 版本过低 使用 nvm 升级：nvm install 20 && nvm use 20

Q3: 网络连接超时 配置代理服务器，或使用国内镜像源切换到国产模型 API。

Q4: API Key 无效 检查 Key 是否正确复制（无多余空格），确认 Key 未过期且余额充足。

Q5: 响应速度慢 切换到轻量级模型（如 glm-4.5-air），减少上下文文件数量，或启用本地缓存。

八、安全与隐私考虑

8.1 API Key 安全

• 使用环境变量存储 Key，不要提交到 Git
• 定期轮换 API Key
• 设置使用限额告警

8.2 代码隐私保护

• 敏感项目建议使用本地部署模型
• 审查 Claude 修改的代码再提交
• 禁用不必要的文件访问权限

8.3 宪法式 AI 安全机制

Claude Code 内置 Constitutional AI 机制，拒绝生成恶意代码，避免执行危险命令，并提示潜在安全风险。

九、总结

Claude Code 作为前沿的 AI 编程工具，核心价值在于效率提升和质量保障。随着 MCP 协议标准化和多 Agent 协作的发展，它正从辅助工具向智能代理进化。对于开发者而言，尽早采用 AI 辅助编程是必然趋势，但也要保持理性，建立完善的代码审查机制，确保安全第一。