Windows (Git Bash) 平台指南

本教程以 Windows + Git Bash 为主线平台。本页汇总所有 Windows 特有的配置要点和常见问题。

环境准备

必装软件

# 1. Git for Windows（包含 Git Bash）
# 下载地址：https://gitforwindows.org/
# 安装时勾选 "Git Bash Here" 和 "Use Git from the Windows Command Line"

# 2. Node.js 18+
# 下载地址：https://nodejs.org/
# 推荐使用 LTS 版本

# 3. Claude Code CLI
npm install -g @anthropic-ai/claude-code

可选工具

# jq - JSON 处理工具（Hooks 章节需要）
# 方式一：通过 Chocolatey
choco install jq

# 方式二：直接下载
# 从 https://jqlang.github.io/jq/download/ 下载 jq-win64.exe
# 重命名为 jq.exe，放入 PATH 中的目录

# Python 3.10+（Agent SDK 章节需要）
# 下载地址：https://www.python.org/downloads/

Git Bash 特有注意事项

路径格式

Git Bash 使用 Unix 风格的路径格式，但有些场景需要注意：

# Git Bash 中的路径
~/.claude/settings.json           # 等同于 C:/Users/<username>/.claude/settings.json

# 在 CLAUDE.md 中引用路径时，使用正斜杠
src/components/**/*.tsx            # 正确
src\components\**\*.tsx            # 错误 -- 不要用反斜杠

# settings.json 中的路径
"file_path": "src/utils/helper.ts" # 正确

Shell 配置文件

# Git Bash 加载顺序：
# 1. ~/.bash_profile（登录 shell）
# 2. ~/.bashrc（交互式 shell）

# 推荐：在 ~/.bash_profile 中 source ~/.bashrc
echo 'if [ -f ~/.bashrc ]; then source ~/.bashrc; fi' >> ~/.bash_profile

# 设置环境变量
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

换行符问题

# Git 配置：避免 CRLF 导致 hook 脚本执行失败
git config --global core.autocrlf input

# 如果 hook 脚本报错 "/bin/bash^M: bad interpreter"
# 用 dos2unix 转换换行符
dos2unix .claude/hooks/*.sh
# 或者用 sed
sed -i 's/\r$//' .claude/hooks/*.sh

各章节 Windows 要点

Ch5 Hooks -- 通知音

# Windows 下在 hook 脚本中播放通知音
powershell.exe -Command "[System.Media.SystemSounds]::Asterisk.Play()"

# 或者通过 PowerShell 播放自定义音频文件
powershell.exe -Command "(New-Object Media.SoundPlayer 'C:/path/to/sound.wav').PlaySync()"

Ch5 Hooks -- 脚本执行

# Git Bash 中 hook 脚本需要 bash shebang
#!/bin/bash

# 确保脚本有执行权限
chmod +x .claude/hooks/*.sh

# 如果使用 PowerShell 作为 hook 处理器，
# 在 settings.json 中这样配置：
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "powershell.exe -File .claude/hooks/lint.ps1"
      }]
    }]
  }
}

Ch9 Agent Teams -- 显示模式

# Windows 原生不支持 tmux，Agent Teams 只能用 in-process 模式
# 这意味着所有 teammate 的输出在同一个终端中

# 替代方案 1：使用 Windows Terminal 的多标签页
# 替代方案 2：使用 WSL2 + tmux
wsl --install
# 在 WSL 中安装 tmux
sudo apt install tmux

Ch10 权限 -- Managed Policy 路径

# Windows 上的 managed policy 路径
# C:\Program Files\ClaudeCode\managed-settings.json
# C:\Program Files\ClaudeCode\managed-settings.d\*.json
# C:\Program Files\ClaudeCode\CLAUDE.md

# 需要管理员权限才能写入该目录

常见问题

Q：Claude Code 在 Git Bash 中无法启动

# 检查 Node.js 是否在 PATH 中
node --version
npm --version

# 检查 Claude Code 是否安装成功
claude --version

# 如果提示 "command not found"，检查 npm 全局安装目录
npm config get prefix
# 确保该路径下的 bin/ 子目录在 PATH 中

Q：Hook 脚本运行报错

# 1. 检查换行符
file .claude/hooks/your-hook.sh
# 如果显示 "CRLF"，转换为 LF
sed -i 's/\r$//' .claude/hooks/your-hook.sh

# 2. 检查执行权限
chmod +x .claude/hooks/your-hook.sh

# 3. 检查 shebang 行
head -1 .claude/hooks/your-hook.sh
# 应该是 #!/bin/bash

Q：$CLAUDE_PROJECT_DIR 路径格式

# 在 Git Bash 中，这个变量使用 Unix 风格路径
echo $CLAUDE_PROJECT_DIR
# 输出：/d/projects/my-project

# 如果需要传给 Windows 程序，可能需要转换
# cygpath -w "$CLAUDE_PROJECT_DIR"
# 输出：D:\projects\my-project

Q：PowerShell Tool 支持

# Claude Code 支持使用 PowerShell 作为 Bash 工具的替代
# 设置以下环境变量启用
export CLAUDE_CODE_USE_POWERSHELL_TOOL=1

# 这会让 Claude 使用 PowerShell 而非 bash 执行命令
# 适合需要 Windows 原生命令的场景