摘要：本文档详细记录了在 Windows 环境下，将 Claude Code 从 C 盘完整迁移到 D 盘（D:appClaude-code）的全流程操作。内容涵盖系统环境前置要求、旧版卸载备份、新版安装、配置文件与环境变量设置、验证步骤以及踩坑经验。所有命令均在 Windows PowerShell 5.1 中验证通过，旨在解决 C 盘空间占用问题并实现多盘符规范管理。

一、 系统环境前置要求

1.1 当前系统环境信息

重要说明：本文档中的命令均在 Windows PowerShell 5.1 (C:WindowsSystem32WindowsPowerShellv1.0powershell.exe) 中执行。PowerShell 5.1 不支持 && 作为语句分隔符，需使用 ; 分号代替。

1.2 Node.js 安装（如未安装）

Claude Code 运行依赖 Node.js，需要 v18+ 版本。

从 https://nodejs.org/ 下载 LTS 版本（推荐 v20+）。

安装时务必勾选 "Add to PATH"。

验证安装：

node -v   # 应输出 v20.x.x 或更高
npm -v    # 应输出 10.x.x 或更高

1.3 Git 安装（如未安装）

Claude Code 的 plugins 和 marketplaces 依赖 Git 克隆仓库。

从 https://git-scm.com/download/win 下载。

安装时保持默认选项即可。

验证安装：

git --version  # 应输出 git version 2.x.x

1.4 PowerShell Core 安装（可选）

如果需要 PowerShell 7.x（pwsh），可通过以下方式安装：

winget install Microsoft.PowerShell

验证：pwsh -v（输出 PowerShell 7.5.4 等）

1.5 关于 npm 版本

npm 11.x 自带于 Node.js v24。若使用较低 Node.js 版本，可通过 npm install -g npm@latest 升级。Claude Code 的 npm install --prefix 方式安装不依赖全局 npm 特殊功能，常规版本即可。

二、 卸载旧版 Claude Code

2.1 查看当前安装情况

在卸载之前，先确认旧版安装的位置和版本：

# 查看 claude 命令所在路径
where claude

# 查看全局安装的包版本
npm list -g @anthropic-ai/claude-code

# 查看 C 盘上的 Claude Code 相关文件
Get-ChildItem -Path "C:UsersAdministrator" -Filter ".claude*" -Force
Get-ChildItem -Path "C:UsersAdministrator.claude" -Force

旧版安装情况示例：

• 可执行文件：C:UsersAdministratorAppDataRoamingnpmclaude.cmd
• npm 包位置：C:UsersAdministratorAppDataRoamingnpmnode_modules@anthropic-aiclaude-code
• 数据目录：C:UsersAdministrator.claude（包含 sessions、cache、plugins、skills、telemetry 等）
• 用户状态：C:UsersAdministrator.claude.json
• 临时文件：C:UsersAdministratorAppDataLocalTempclaude

2.2 使用 npm 卸载旧版全局包

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

此命令会移除：

• C:UsersAdministratorAppDataRoamingnpmclaude
• C:UsersAdministratorAppDataRoamingnpmclaude.cmd
• C:UsersAdministratorAppDataRoamingnpmclaude.ps1
• C:UsersAdministratorAppDataRoamingnpmnode_modules@anthropic-aiclaude-code

2.3 备份重要配置文件

清理前务必先备份！ 将关键配置备份到 D 盘目标目录：

# 先创建目标目录
New-Item -Path "D:appClaude-codedata" -ItemType Directory -Force

# 备份 settings.json（含 API 配置、插件设置等）
Copy-Item "C:UsersAdministrator.claudesettings.json" "D:appClaude-codesettings.json.bak" -Force

# 备份 statusline-command.sh（状态栏配置脚本）
Copy-Item "C:UsersAdministrator.claudestatusline-command.sh" "D:appClaude-codestatusline-command.sh.bak" -Force

2.4 清理 C 盘旧数据目录

备份完成后，删除占用空间的旧数据目录：

# 删除旧的数据目录（sessions、cache、plugins、skills、telemetry等大量文件）
Remove-Item -Path "C:UsersAdministrator.claude" -Recurse -Force

# 清理临时文件
Remove-Item -Path "C:UsersAdministratorAppDataLocalTempclaude" -Recurse -Force -ErrorAction SilentlyContinue

2.5 保留 .claude.json（不要删除）

重要提示：不要删除 C:UsersAdministrator.claude.json！

• 这是用户状态文件（含 hasCompletedOnboarding: true、项目历史、启动计数等）。
• 位置固定在用户目录下，不受 CLAUDE_CONFIG_DIR 环境变量控制。
• 删除后会重新触发首次引导（onboarding）流程。
• 文件很小（约 10~50KB），不占空间。

三、 安装最新版 Claude Code 到 D 盘

3.1 创建目标目录结构

如果在第 2.3 步备份时已创建，可跳过此步：

New-Item -Path "D:appClaude-codedata" -ItemType Directory -Force

3.2 使用 npm --prefix 本地安装

此方式不会在 C 盘的全局 npm 目录中生成文件，所有内容都在 D 盘指定目录下：

npm install --prefix "D:appClaude-code" @anthropic-ai/claude-code@latest

安装完成后目录结构：

D:appClaude-code
├── data                        ← 配置和数据目录（由 CLAUDE_CONFIG_DIR 指向）
│   └── settings.json            ← 兜底配置文件（默认路径不存在时读取此文件）
├── node_modules
│   ├── .bin
│   │   ├── claude.cmd           ← Windows 可执行文件
│   │   └── claude               ← Unix 可执行文件
│   └── @anthropic-ai
│       └── claude-code         ← 程序本体
├── package.json
├── package-lock.json
├── settings.json.bak            ← 旧配置备份
└── statusline-command.sh.bak    ← 旧状态栏脚本备份

3.3 验证安装

& "D:appClaude-codenode_modules.binclaude.cmd" --version
# 输出示例: 2.1.150 (Claude Code)

四、 配置环境变量

本节设置的环境变量均为 用户级 环境变量（写入注册表），仅当前用户生效。

4.1 设置 CLAUDE_CONFIG_DIR（必须）

让 Claude Code 的数据文件（sessions、cache、history、plugins等大体积文件）存储到 D 盘：

[System.Environment]::SetEnvironmentVariable("CLAUDE_CONFIG_DIR", "D:appClaude-codedata", "User")

4.2 添加 PATH（必须）

让 claude 命令在任何目录下都可直接使用：

$currentPath = [System.Environment]::GetEnvironmentVariable("Path", "User")
$newBin = "D:appClaude-codenode_modules.bin"
if ($currentPath -notlike "*$newBin*") {
    [System.Environment]::SetEnvironmentVariable("Path", "$newBin;$currentPath", "User")
}

4.3 不要设置 ANTHROPIC_* 为系统环境变量

严重警告：ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、ANTHROPIC_DEFAULT_SONNET_MODEL 等 API 相关变量绝对不能设为系统环境变量！

• 系统环境变量优先级 高于 settings.json 中的 env 字段。
• 设置后会导致 ccswitch 切换模型不生效（因为被环境变量覆盖）。
• 手动修改 settings.json 也不生效（同理）。
• API 配置只应通过 settings.json 的 env 字段管理。

4.4 环境变量汇总

最终应设置的用户环境变量（仅此两项）：

五、 配置 settings.json

5.1 配置文件作用说明

settings.json 是 Claude Code 的核心配置文件，包含：

• env 字段：API 密钥、模型名称、Base URL 等（Claude Code 启动时自动注入为进程环境变量）。
• enabledPlugins：启用的插件列表。
• extraKnownMarketplaces：第三方插件市场源。
• language：界面语言。

5.2 MiniMax API 配置（跳过官方登录）

在 D:appClaude-codedatasettings.json 中写入：

{
  "enabledPlugins": {
    "gopls-lsp@claude-plugins-official": true,
    "superpowers@claude-plugins-official": true
  },
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-cp-你的API密钥",
    "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M2.7"
  },
  "extraKnownMarketplaces": {
    "everything-claude-code": {
      "source": {
        "source": "git",
        "url": "https://github.com/affaan-m/everything-claude-code.git"
      }
    },
    "superpowers-marketplace": {
      "source": {
        "source": "git",
        "url": "https://github.com/obra/superpowers-marketplace.git"
      }
    }
  },
  "language": "zh-cn"
}

关于跳过官方登录： 只要 env 中配置了 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL，Claude Code 启动时就不会要求官方 Anthropic 账号登录，直接使用配置的第三方 API。

5.3 配置文件优先级机制（重要）

Claude Code 的 settings.json 读取遵循降级策略：

行为规则：

• 当默认路径 ~/.claude/settings.json 不存在时 → 读取 CLAUDE_CONFIG_DIR 下的配置。
• 当 ccswitch 创建了默认路径的配置后 → 默认路径优先生效，覆盖 CLAUDE_CONFIG_DIR。
• 两者并存不冲突，ccswitch 正常工作。
• ccswitch 生成的配置内容是完整正确的，不是只改了模型字段。

六、 验证

6.1 新终端中验证（重要：必须新开终端）

环境变量修改后已打开的终端不会自动刷新，必须新开终端窗口：

# 新开的 PowerShell 终端中直接执行
claude --version
# 输出: 2.1.150 (Claude Code)

6.2 测试 API 连通性

echo "回复OK两个字" | claude -p "回复OK两个字"
# 应返回: OK

6.3 若当前终端找不到 claude 命令

环境变量修改后已打开的终端不会自动刷新 PATH，可手动刷新当前会话：

$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "User") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "Machine")
$env:CLAUDE_CONFIG_DIR = "D:appClaude-codedata"

七、 踩坑经验总结

7.1 ANTHROPIC_* 系统环境变量会覆盖配置文件

• 问题：如果将 ANTHROPIC_AUTH_TOKEN 等设为用户级系统环境变量，它们会覆盖 settings.json 中的同名配置。
• 影响：ccswitch 切换模型不生效；手动修改 settings.json 不生效。
• 解决：只通过 settings.json 的 env 字段管理这些变量，不设系统环境变量。

如果已误设，清除方法：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", $null, "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", $null, "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_DEFAULT_HAIKU_MODEL", $null, "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_DEFAULT_OPUS_MODEL", $null, "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_DEFAULT_SONNET_MODEL", $null, "User")

7.2 PowerShell 终端不自动刷新用户级 PATH

问题：通过 [System.Environment]::SetEnvironmentVariable(...) 设置的环境变量写入注册表，但不会立即在已打开的终端中生效。

解决：必须新开终端窗口。或在当前终端手动刷新：

$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "User") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "Machine")

7.3 .claude.json 不受 CLAUDE_CONFIG_DIR 控制

C:UsersAdministrator.claude.json 是固定路径的用户状态文件，与 CLAUDE_CONFIG_DIR 无关。该文件始终在 C 盘用户目录下创建和读取，体积很小，不用管它。

7.4 settings.json 的降级读取逻辑

• CLAUDE_CONFIG_DIR 控制 sessions、cache、history 等大文件存储位置。
• ~/.claude/settings.json（默认路径）在读取优先级上高于 CLAUDE_CONFIG_DIR/settings.json。
• 两者是降级关系，不是互斥关系。
• ccswitch 写入默认路径后自动生效，不需要额外操作。

7.5 claude.cmd 不支持 --no-input 选项

非交互式调用不能使用 --no-input，需通过管道方式：

echo "你的prompt" | claude -p "你的prompt"

7.6 清理前必须备份

删除 .claude 目录前，务必先备份 settings.json（含 API 配置）和其他重要文件，否则需要重新配置所有 API 参数和插件设置。

八、 最终文件清单

C 盘保留文件

• C:UsersAdministrator.claude.json — 用户状态文件（保留，不可控制位置）
• C:UsersAdministrator.claudesettings.json — ccswitch 使用时会自动创建（正常，高优先级）

D 盘安装文件

• D:appClaude-codenode_modules — Claude Code 程序本体
• D:appClaude-codedatasettings.json — 兜底配置文件
• D:appClaude-codedatasessions — 会话数据（自动创建）
• D:appClaude-codedatacache — 缓存数据（自动创建）
• D:appClaude-codedataplugins — 插件数据（自动创建）
• D:appClaude-codesettings.json.bak — 旧配置备份（可删）
• D:appClaude-codestatusline-command.sh.bak — 旧状态栏脚本备份（可删）

用户环境变量（仅两项）

• CLAUDE_CONFIG_DIR = D:appClaude-codedata
• PATH 中包含 D:appClaude-codenode_modules.bin

九、 后续维护

9.1 升级 Claude Code

npm update --prefix "D:appClaude-code" @anthropic-ai/claude-code
# 或指定版本
npm install --prefix "D:appClaude-code" @anthropic-ai/[email protected]

9.2 切换模型

两种方式：

1. ccswitch（推荐）：自动修改 C:UsersAdministrator.claudesettings.json，高优先级直接生效。
2. 手动编辑：修改 D:appClaude-codedatasettings.json 中 env 字段的模型名称（需确保默认路径配置不存在或已同步修改）。

9.3 完全卸载

# 删除安装目录
Remove-Item -Path "D:appClaude-code" -Recurse -Force

# 删除环境变量
[System.Environment]::SetEnvironmentVariable("CLAUDE_CONFIG_DIR", $null, "User")

# 从 PATH 中移除
$path = [System.Environment]::GetEnvironmentVariable("Path", "User")
$path = $path -replace [regex]::Escape("D:appClaude-codenode_modules.bin;"), ""
[System.Environment]::SetEnvironmentVariable("Path", $path, "User")

# 可选：删除用户状态和默认路径配置
Remove-Item "C:UsersAdministrator.claude.json" -Force
Remove-Item "C:UsersAdministrator.claude" -Recurse -Force -ErrorAction SilentlyContinue

十、 高级配置与扩展指南

在完成基础迁移与验证后，以下进阶内容可帮助你进一步定制 Claude Code 的使用体验，涵盖插件管理、状态栏自定义及多环境切换。

10.1 插件市场管理与安装

文档中配置的 extraKnownMarketplaces 仅为声明市场源，实际安装插件需通过命令行或交互式界面完成。

查看可用插件列表：

claude plugins list --marketplace everything-claude-code

安装指定插件：

claude plugins install @
# 示例：安装 superpowers 市场的代码审查插件
claude plugins install code-review@superpowers-marketplace

禁用/启用已安装插件：直接编辑 D:appClaude-codedatasettings.json 中的 enabledPlugins 字段，将对应插件值设为 false 即可临时禁用，无需卸载。

10.2 状态栏自定义脚本

备份的 statusline-command.sh 是 Claude Code 终端状态栏的自定义脚本，支持显示当前模型、Token 消耗、Git 分支等信息。

将备份脚本复制到 D 盘数据目录：

Copy-Item "D:appClaude-codestatusline-command.sh.bak" "D:appClaude-codedatastatusline-command.sh"

编辑脚本内容，支持 Bash 语法，输出内容会实时渲染在终端底部状态栏。

若脚本未生效，检查文件编码是否为 UTF-8 无 BOM，Windows 下建议使用 VS Code 转换编码。

10.3 多 API 环境快速切换

除 ccswitch 外，可通过创建多个配置文件实现开发/测试环境的快速切换，避免频繁修改主配置。

在 D:appClaude-codedata 下创建备用配置：

Copy-Item "D:appClaude-codedatasettings.json" "D:appClaude-codedatasettings.dev.json"

修改备用配置中的 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 为测试环境参数。

切换时仅需重命名文件，或通过临时环境变量覆盖（仅当前会话生效）：

$env:CLAUDE_SETTINGS_PATH = "D:appClaude-codedatasettings.dev.json"
claude

十一、 常见问题排查手册

十二、 安全与维护建议

1. API 密钥安全：settings.json 中包含明文 API 密钥，请勿将该文件提交至公开仓库。建议在 Git 项目中添加 .claude/ 和 settings.json 到 .gitignore。
2. 定期清理缓存：D:appClaude-codedatacache 和 sessions 会随使用持续增长，可每月手动清理过期文件，或编写定时任务自动清理 30 天前的会话数据。
3. 配置版本管理：建议将 settings.json 纳入私有 Git 仓库管理，记录每次修改历史，方便回滚误操作。
4. 升级前备份：执行 npm update 前，务必备份 data/settings.json，防止新版本覆盖自定义配置。
5. 权限最小化：D 盘安装目录仅当前用户需要读写权限，无需管理员权限，避免恶意程序篡改核心文件。

结语

本指南完整覆盖了 Claude Code 在 Windows 环境下从 C 盘迁移至 D 盘的全生命周期操作，从环境准备、卸载备份、安装配置到验证维护、进阶扩展，所有步骤均基于官方文档与实测经验整理。遵循本指南可实现程序与系统盘的彻底解耦，同时保留完整的个性化配置与插件生态。建议在操作前通读全文，重点标记警告与避坑章节，确保迁移过程平稳无误。