claude-code/BUILD.md

Claude Code Java — 构建与安装指南

前置要求

依赖	版本	说明
JDK	25+	必须，推荐 Oracle JDK 25 或 OpenJDK 25
Maven	3.9+	必须，下载地址
API Key	-	OpenAI / Anthropic / 兼容 API 的密钥

⚠️ JDK 25 是必须的，项目使用了 preview 特性（如 pattern matching、string templates）。

---

快速开始（开发模式）

适合开发和调试，通过 Maven 直接运行：

# 1. 设置 JDK
export JAVA_HOME=/path/to/jdk-25    # Linux/macOS
set JAVA_HOME=C:\Dev\jdk-25.0.2     # Windows

# 2. 设置 API Key
export AI_API_KEY=your-api-key       # Linux/macOS
set AI_API_KEY=your-api-key          # Windows

# 3. 运行
mvn spring-boot:run

📌 开发模式下，工作目录（AI 操作的目录）为执行 mvn 命令的目录。

---

构建发行版（推荐用于日常使用）

发行版使用 jlink 创建精简 JRE，打包为独立可执行程序，无需目标机器安装 JDK。

Windows

# 构建
.\packaging\build-dist.ps1 -JavaHome "C:\Dev\jdk-25.0.2"

# 或跳过 Maven 构建（已有 jar 的情况）
.\packaging\build-dist.ps1 -JavaHome "C:\Dev\jdk-25.0.2" -SkipBuild

Linux / macOS

# 构建
JAVA_HOME=/path/to/jdk-25 ./packaging/build-dist.sh

# 或跳过 Maven 构建
JAVA_HOME=/path/to/jdk-25 ./packaging/build-dist.sh --skip-build

构建输出

dist/
├── bin/
│   ├── claude-code          # Unix 启动脚本 (Linux/macOS)
│   └── claude-code.cmd      # Windows 启动脚本
├── lib/
│   └── claude-code-java.jar # Spring Boot fat jar (~71 MB)
└── runtime/                 # jlink 精简 JRE (~49 MB)
    ├── bin/
    ├── conf/
    ├── lib/
    └── release

总大小约 120 MB（对比完整 JDK ~350 MB）。

---

安装到系统 PATH

将 dist/bin 加入系统 PATH 后，可在任意目录直接使用 claude-code 命令。

Windows

方法 1：CMD 临时生效（当前终端）

set PATH=C:\path\to\claude-code-java\dist\bin;%PATH%

方法 2：PowerShell 临时生效（当前终端）

$env:PATH = "C:\path\to\claude-code-java\dist\bin;$env:PATH"

方法 3：CMD 永久生效（用户级）

setx PATH "%PATH%;C:\path\to\claude-code-java\dist\bin"

需要重开终端窗口生效。

方法 4：PowerShell 永久生效

$binPath = "C:\path\to\claude-code-java\dist\bin"
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
if ($currentPath -notmatch [regex]::Escape($binPath)) {
    [Environment]::SetEnvironmentVariable("PATH", "$currentPath;$binPath", "User")
    Write-Host "Added to PATH. Restart terminal to take effect."
}

Linux

# 临时生效
export PATH="/path/to/claude-code-java/dist/bin:$PATH"

# 永久生效 — 添加到 ~/.bashrc 或 ~/.zshrc
echo 'export PATH="/path/to/claude-code-java/dist/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

macOS

# 临时生效
export PATH="/path/to/claude-code-java/dist/bin:$PATH"

# 永久生效 — 添加到 ~/.zshrc (macOS 默认 shell 是 zsh)
echo 'export PATH="/path/to/claude-code-java/dist/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

验证安装

# 在任意目录执行
claude-code           # Linux/macOS
claude-code.cmd       # Windows CMD
claude-code           # Windows PowerShell (自动找 .cmd)

---

在其他目录使用

安装到 PATH 后，claude-code 可以在任何目录启动。AI 的工作目录就是你启动命令时的当前目录。

# 示例：在项目目录启动，AI 会自动读取该目录的上下文
cd /path/to/my-project
claude-code

# AI 将：
# - 自动加载 ./CLAUDE.md（如果存在）
# - 读取 .git 信息获取项目上下文
# - 所有文件操作基于当前目录

# 示例：在不同项目之间切换
cd ~/projects/web-app && claude-code      # 操作 web-app 项目
cd ~/projects/api-server && claude-code   # 操作 api-server 项目

工作目录说明

场景	工作目录	说明
cd /my-project && claude-code	/my-project	AI 在此目录下操作文件
启动后使用工具	当前目录	bash, file_read 等都基于启动目录
CLAUDE.md 加载	当前目录 + ~/.claude/	项目级 + 全局级自动合并
Git 上下文	当前目录的 .git	自动检测分支、状态、最近提交

---

环境变量

变量	必须	说明	默认值
AI_API_KEY	✅	API 密钥	-
CLAUDE_CODE_PROVIDER	❌	提供者 (openai / anthropic)	openai
AI_BASE_URL	❌	API 基础 URL	按提供者不同
AI_MODEL	❌	模型名称	按提供者不同
AI_MAX_TOKENS	❌	最大生成 Token 数	8096
CLAUDE_CODE_VIM	❌	启用 Vim 编辑模式	0
CLAUDE_CODE_CONTEXT_WINDOW	❌	上下文窗口大小	200000

建议将常用变量配置到 shell profile 中：

# ~/.bashrc 或 ~/.zshrc
export AI_API_KEY="sk-your-key-here"
export CLAUDE_CODE_PROVIDER="openai"
export AI_BASE_URL="https://api.deepseek.com"
export AI_MODEL="deepseek-chat"

Windows 可用 setx 持久化：

setx AI_API_KEY "sk-your-key-here"
setx CLAUDE_CODE_PROVIDER "openai"

---

跨平台构建注意事项

jlink 创建的 JRE 是 平台相关 的。在 Windows 上构建的 dist/ 只能在 Windows 上运行。

如果需要为多个平台构建：

构建平台	产出	可运行平台
Windows x64	dist/runtime/ (Windows JRE)	Windows x64
Linux x64	dist/runtime/ (Linux JRE)	Linux x64
macOS ARM	dist/runtime/ (macOS JRE)	macOS ARM (M1/M2/M3)
macOS x64	dist/runtime/ (macOS JRE)	macOS Intel

💡 lib/claude-code-java.jar 是跨平台的，只有 runtime/ 需要针对每个平台构建。

如果在 CI/CD 中构建，可以在 GitHub Actions 中使用 matrix strategy 分别在 ubuntu-latest, windows-latest, macos-latest 上构建。

---

常见问题

Q: 启动时报 "OpenAI API key must be set"

设置 AI_API_KEY 环境变量：

export AI_API_KEY="your-key"

Q: Windows 终端中文乱码

发行版启动脚本已自动执行 chcp 65001。如果仍有问题，手动运行：

chcp 65001

Q: 如何使用 Anthropic API 而不是 OpenAI?

export CLAUDE_CODE_PROVIDER="anthropic"
export AI_API_KEY="sk-ant-your-key"
export AI_MODEL="claude-sonnet-4-20250514"

Q: 如何使用 DeepSeek / Azure OpenAI 等兼容 API?

export CLAUDE_CODE_PROVIDER="openai"
export AI_BASE_URL="https://api.deepseek.com"
export AI_MODEL="deepseek-chat"
export AI_API_KEY="your-deepseek-key"

Q: dist/ 目录可以复制到其他机器吗?

可以，只要目标机器的操作系统和 CPU 架构与构建机器一致。dist/ 是完全自包含的，不需要安装 JDK。

Q: 如何更新?

重新执行构建脚本覆盖 dist/ 目录即可：

git pull
./packaging/build-dist.sh        # 或 .ps1