


## 前言
最近一直在用 Claude Code 做本地项目的代码重构、测试文档批量迭代，从最开始的环境搭建踩坑，到国内大模型对接、频繁的权限确认弹窗，再到后期长上下文卡顿停滞，前后踩了不少实坑。

这篇文章把 Windows 平台下 Claude Code 从安装、核心配置、中文化、权限管控到性能优化的全流程整理清楚，所有配置代码均可直接复制复用，帮大家快速落地，少走弯路。

## 一、安装：三种方式与自定义目录方案
Claude Code 官方提供了多种安装方式，Windows 下推荐优先用 WinGet，其次是官方 PowerShell 脚本；如果想自定义安装目录、避开C盘，也可以手动部署二进制文件。

### 1. 一键安装方案
#### WinGet 安装（国内网络友好）
Windows 11 自带包管理器，无需翻墙，一行命令完成安装：
```powershell
winget install Anthropic.ClaudeCode
```

#### 官方 PowerShell 脚本
适合需要紧跟官方版本的场景，以管理员身份打开 PowerShell 执行：
```powershell
irm https://claude.ai/install.ps1 | iex
```
默认安装路径为 `C:\Users\用户名\.local\bin`，安装完成后重启终端即可调用 `claude` 命令。

### 2. 指定版本安装
如果不想用最新版，需要固定版本迭代，可以在脚本后追加版本号：
```powershell
# 安装指定版本
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89

# WinGet 指定版本
winget install Anthropic.ClaudeCode --version 2.1.89
```

### 3. 自定义安装目录（迁移出C盘）
官方脚本默认强制安装到C盘用户目录，想放到D盘自定义路径，推荐手动二进制部署：
1. 去 GitHub Releases 下载 `claude-code-windows-x64.zip`
2. 解压到目标路径，例如 `D:\Tools\ClaudeCode`
3. 将该路径添加到系统环境变量 `Path` 中
4. 新增环境变量 `CLAUDE_CODE_INSTALL_DIR`，值为你的安装路径

如果已经安装在C盘想迁移，直接剪切 `.local\bin` 文件夹到目标目录，更新 Path 环境变量和上述安装目录变量即可，同时建议关闭自动更新避免回迁C盘。
![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-10298071/15e831e918b2ef217fcba19894f5cd12.png)

## 二、核心配置：对接国内云端模型
Claude Code 默认对接官方 Claude 模型，国内环境无法直连，我们可以通过兼容接口对接阿里云百炼等国内平台，这里以 Qwen3.6-27B 为例。

### 1. 全局配置文件
所有持久化配置都写在 `C:\Users\用户名\.claude\settings.json` 中，没有文件就手动新建。下面是可直接复制的完整配置模板，替换密钥即可使用：

```json
{
  "language": "zh-CN",
  "autoCompact": false,
  "autoUpdate": false,
  "permissions": {
    "files": "allow",
    "commands": "allow"
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://dashscope.aliyuncs.com/apps/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-替换为你的阿里云DashScope密钥",
    "ANTHROPIC_MODEL": "qwen3.6-27b",
    "API_TIMEOUT_MS": "600000"
  }
}
```

### 2. 关键参数说明
- `ANTHROPIC_BASE_URL`：模型接口地址，阿里云兼容接口固定为此地址，**末尾不能加 /v1**，否则会404
- `ANTHROPIC_AUTH_TOKEN`：平台生成的 API 密钥
- `ANTHROPIC_MODEL`：指定调用的具体模型名称
- `API_TIMEOUT_MS`：接口超时时间，长文档处理建议设为600000（10分钟），避免频繁超时停滞

> 踩坑提醒：如果调用时报 `Arrearage` 400错误，说明账户欠费或免费额度耗尽，充值后重启终端即可恢复。

## 三、中文化：界面与输出全中文
很多朋友刚装完是英文界面，甚至AI回复也默认英文，分两步设置即可实现全中文体验。

### 1. 界面语言设置
#### 全局永久生效
在 `settings.json` 根节点添加配置，重启终端后默认中文界面：
```json
"language": "zh-CN"
```

#### 会话内临时切换
进入 claude 交互窗口后执行命令，立即生效：
```
/language zh-CN
```

### 2. 强制AI输出中文
界面中文 ≠ AI回复中文，想让所有代码注释、文档、说明都输出中文，添加全局系统提示词即可：
```json
"systemPrompt": "你全程使用简体中文回复，所有代码注释、文档、清单、说明文字全部输出中文，禁止英文解释"
```

也可以在会话内临时指定：
```
之后所有回答、编写文档、写代码注释全部只用简体中文输出
```

## 四、权限优化：取消每次执行确认弹窗
默认安全策略下，AI执行任何命令、修改文件都会弹出确认框，频繁操作非常打断流程，可以根据需求放开权限。

### 1. 会话内临时放行
```
# 放行所有Python脚本
/permissions commands allow python

# 放行全部系统命令
/permissions commands allow all

# 放行所有文件读写
/permissions files allow all
```

### 2. 全局永久配置
在 `settings.json` 的 `permissions` 节点配置，重启后永久生效：
```json
"permissions": {
  "files": "allow",
  "commands": "allow"
}
```

### 3. 安全折中：精细白名单
不想全开风险，可以只放行常用命令，拦截高危操作：
```json
"permissions": {
  "files": "allow",
  "commands": {
    "allow": ["python*", "python3*"],
    "deny": ["rm*", "del*", "format*", "rd*"]
  }
}
```
Python 脚本自动执行无弹窗，删除、格式化等高风险操作依旧保留二次确认。

## 五、性能优化：解决卡顿停滞问题
长文档处理、大项目扫描时，经常会出现 `Brewed` `Stalled` `Churned` 等状态并长时间卡住，下面是对应原因和优化方案。

### 1. 状态词含义说明
- **Work**：正常运算中，无需处理
- **Brewed**：后台加载上下文、读取解析大量文件，属于高负载等待
- **Churned**：AI反复迭代思考、校验逻辑，长任务正常现象
- **Crunched**：自动压缩超长对话上下文，节省token
- **Stalled**：真正的停滞卡死，通常是网络延迟、接口限流、请求超时导致

### 2. 针对性优化方案
#### ① 及时清空冗余上下文
每完成一个大任务就执行一次清空，避免历史记录越堆越慢：
```
/clear
```

#### ② 拆分大任务，控制上下文大小
不要一次性让AI读取十几个大文件、同时完成生成+校验+导出多步任务，拆分成单步执行，大幅降低加载压力，减少 `Brewed` 等待时间。

#### ③ 关闭自动压缩，手动管控
关闭自动上下文压缩，避免后台无感知卡顿，需要时手动执行：
```json
"autoCompact": false
```
手动压缩命令：
```
/compact
```

#### ④ 拉长超时阈值
长文档处理容易超时触发 `Stalled`，把超时时间拉长到10分钟：
```json
"API_TIMEOUT_MS": "600000"
```

## 六、配置技巧：JSON 注释与参数屏蔽
标准 JSON 不支持注释，但 Claude Code 的配置解析器做了放宽，可以直接用 `//` 写注释、屏蔽备用配置。

### 1. 单行注释与参数屏蔽
```json
{
  "language": "zh-CN", // 界面简体中文
  "autoCompact": false, // 关闭自动上下文压缩
  // "ANTHROPIC_MODEL": "qwen3.6-plus", // 临时屏蔽，备用模型
  "ANTHROPIC_MODEL": "qwen3.6-27b"
}
```

### 2. 多套配置切换模板
可以把备用模型配置注释掉，需要时快速切换：
```json
"env": {
  // 阿里云Qwen配置（当前启用）
  "ANTHROPIC_BASE_URL": "https://dashscope.aliyuncs.com/apps/anthropic",
  "ANTHROPIC_AUTH_TOKEN": "sk-阿里云密钥",
  "ANTHROPIC_MODEL": "qwen3.6-27b",

  // Claude官方配置（已屏蔽）
  // "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
  // "ANTHROPIC_AUTH_TOKEN": "sk-Claude官方密钥",
  // "ANTHROPIC_MODEL": "claude-3.7-sonnet"
}
```

> 注意：`//` 注释仅 Claude Code 自身识别，把配置复制到其他标准JSON工具时，需要先删掉注释避免语法报错。

## 七、VSCode 插件配套配置
日常写代码更推荐用 VSCode 插件版，核心配置和 CLI 版通用，在 VSCode 的 `settings.json` 中添加即可：

```json
"claudeCode.language": "zh-CN",
"claudeCode.autoApproveCommands": true,
"claudeCode.autoApproveFileEdits": true,
"claudeCode.defaultModel": "qwen3.6-27b",
"claudeCode.environmentVariables": [
    {"name":"ANTHROPIC_BASE_URL","value":"https://dashscope.aliyuncs.com/apps/anthropic"},
    {"name":"ANTHROPIC_AUTH_TOKEN","value":"sk-你的密钥"},
    {"name":"ANTHROPIC_MODEL","value":"qwen3.6-27b"}
]
```
保存后重载 VSCode 窗口，即可实现和 CLI 版一致的全中文、自动放行、国内模型调用体验。

## 写在最后
Claude Code 作为本地代码助手，优势在于能深度操作本地文件、执行脚本，非常适合批量文档处理、项目重构、代码审查这类场景。

国内环境使用的核心痛点就是网络对接、权限繁琐、长任务卡顿，按照本文配置优化后，基本可以做到开箱即用、流畅运行。如果有其他场景的问题，也欢迎一起交流。

最近一直在用 Claude Code 做本地项目的代码重构、测试文档批量迭代，从最开始的环境搭建踩坑，到国内大模型对接、频繁的权限确认弹窗，再到后期长上下文卡顿停滞，前后踩了不少实坑。

Windows 下 Claude Code 落地全指南：从安装配置到避坑优化

人工智能

Windows平台ClaudeCode全流程配置指南：涵盖WinGet安装、自定义目录迁移、阿里云Qwen模型对接、全中文界面设置、权限弹窗优化及长任务卡顿解决方案。提供可直接复制的settings.json配置模板，解决国内网络连接、超时停滞等核心痛点，实现开箱即用的本地AI编程体验。

网络延迟

包管理器

文档处理

代码解释

Windows

Python

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Windows 下 Claude Code 落地全指南：从安装配置到避坑优化-腾讯云开发者社区-腾讯云

Windows 下 Claude Code 落地全指南：从安装配置到避坑优化

Windows 下 Claude Code 落地全指南：从安装配置到避坑优化

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐