本教程旨在为 Windows 用户提供一份详尽、可靠的指南，帮助你将 Claude Code 从 C 盘完整迁移至 D 盘，以解决 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 和 npm 命令。
• 安装完成后，打开 PowerShell 验证安装是否成功。

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 安装程序。
• 安装时，保持默认选项即可。
• 安装完成后，验证 Git 是否可用。

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 命令升级 npm 到最新版本。Claude Code 通过 npm install --prefix 方式安装，不依赖全局 npm 的特定功能，因此常规版本即可满足要求。

二、 卸载旧版 Claude Code

在开始全新安装之前，我们需要彻底卸载旧版本的 Claude Code，并备份重要的配置文件，以确保迁移过程干净、无残留。

2.1 查看当前安装情况

首先，执行以下命令确认旧版 Claude Code 的安装位置和版本信息，以便后续精准操作。

# 查看 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 全局安装目录中移除旧版 Claude Code。

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

此命令会移除以下文件：

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

2.3 备份重要配置文件

在进行清理操作前，务必备份你之前自定义的配置，以免丢失。

# 先创建目标目录
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 盘旧数据目录

备份完成后，可以安全地删除 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 环境变量控制。
• 删除该文件后，重新启动 Claude Code 时会触发首次引导（onboarding）流程，造成不便。
• 此文件体积很小（约 10~50KB），几乎不占用空间，请放心保留。

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

完成清理后，我们开始将 Claude Code 全新安装到 D 盘指定目录，这是实现迁移的核心步骤。

3.1 创建目标目录结构

如果在第 2.3 步备份时已经创建了目录，可以跳过此步。否则，请执行以下命令创建。

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

3.2 使用 npm --prefix 本地安装

此方式会将 Claude Code 安装到 D 盘的指定文件夹下，而不会在 C 盘的全局 npm 目录中生成任何文件，从而实现与系统盘的彻底解耦。

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

安装完成后，D 盘目录结构如下：

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 验证安装

安装完成后，运行以下命令确认 Claude Code 是否已正确安装到 D 盘。

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

四、 配置环境变量

为了使 Claude Code 能正确读取 D 盘的配置，并让 claude 命令在全局生效，我们需要配置两个用户级环境变量。

4.1 设置 CLAUDE_CONFIG_DIR（必须）

这个环境变量用于告诉 Claude Code，将所有的数据文件（sessions、cache、history、plugins 等大体积文件）存储到 D 盘的指定目录，从而避免 C 盘空间被持续占用。

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

4.2 添加 PATH（必须）

为了让 claude 命令在任何目录下都可以直接使用，需要将 D 盘的可执行文件目录添加到系统的 PATH 环境变量中。

$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

这个文件是 Claude Code 的核心配置文件，用于管理 API 密钥、模型、插件、语言等核心设置。

5.1 配置文件作用说明

settings.json 主要包含以下关键配置：

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

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

使用第三方 API 可以跳过官方登录流程。在 D:appClaude-codedatasettings.json 文件中写入以下内容，并替换 sk-cp-你的API密钥 为你的实际密钥。

{
  "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 的配置文件读取优先级，可以帮助你更好地理解后续的配置行为。

行为规则：

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

六、 验证

完成所有配置后，我们需要进行验证，确保迁移成功且所有功能正常。

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

环境变量修改后，已打开的终端不会自动刷新，必须新开一个终端窗口，使新设置的环境变量生效。

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

6.2 测试 API 连通性

运行一个简单的测试命令，验证 API 配置是否正确， Claude Code 是否能够正常响应。

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

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

如果你不想新开终端，也可以在当前会话中手动刷新环境变量，使其生效。

$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(...) 设置的环境变量会写入注册表，但不会立即在已打开的终端中生效。

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

$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 参数，需要通过管道方式传递 prompt。

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/claude-code@2.2.0

9.2 切换模型

有两种方式可以切换模型：

1. ccswitch（推荐）：它会自动修改 C:UsersAdministrator.claudesettings.json，该文件具有高优先级，修改后立即生效。
2. 手动编辑：直接修改 D:appClaude-codedatasettings.json 中 env 字段的模型名称。但请注意，如果默认路径的配置文件存在，其优先级更高，你的修改可能不会生效。

9.3 完全卸载

如果你需要彻底移除 Claude Code，可以执行以下命令。

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