docs/getting-started/development-environment.md

<a id="development-environment"></a>

# 开发环境搭建

> 使用方法：Codex CLI 已跑通时，优先让 Codex Agent 读取本节并主动配置剩余环境；Codex CLI 不可用时，再复制下方对应你设备的提示词，粘贴到任意 AI 对话框（ChatGPT、Claude、Gemini 网页版等），让网页 AI 一步步指导你完成配置。

**前置条件**：请先完成 [网络环境配置](network-environment.md)。推荐先完成 [CLI 配置](cli-setup.md)，让 Codex Agent 接管后续开发环境搭建。

---

### 不会操作？先让网页 AI 生成逐步执行版

如果你不知道该选 Windows / WSL / macOS / Linux 哪条路线，打开 ChatGPT / Claude / Gemini 网页版，把下面提示词和本文档全文一起粘贴进去：

```text
我正在按下面这份开发环境搭建文档配置一台新电脑。请你根据我的系统情况，生成一步一步执行流程。

我的系统是：____
我是否已经安装过 WSL / Node.js / npm / Git / Python：____
我希望优先使用 Codex CLI：是

要求：
1. 每一步只做一件事。
2. 明确告诉我在哪个终端执行：PowerShell、Ubuntu 终端、Linux shell 或 macOS Terminal。
3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。
4. 每一步执行后都给一个验证命令或验证方法。
5. 不要假设我已经安装任何前置依赖；按新电脑处理。
6. 如果我后续贴完整报错，请根据当前步骤给出最小修复命令。

下面是完整文档：

[把本文档全文粘贴到这里]
```

### 🪟 Windows 用户提示词

#### 方案 A：WSL2 + Linux 环境（推荐）

> 适合：想要完整 Linux 开发体验，兼容性最好

```
你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 Windows 系统，需要你一步一步指导我通过 WSL2 搭建 Linux 开发环境。

请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：

1. 安装 WSL2（Windows Subsystem for Linux）
2. 在 WSL2 中安装 Ubuntu
3. 配置 Ubuntu 基础环境（更新系统）
4. 安装 nvm 和 Node.js
5. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选
6. 安装基础开发工具（git, python, build-essential, tmux）
7. 配置 Git 用户信息
8. 安装代码编辑器（VS Code 并配置 WSL 插件）
9. 验证所有工具是否正常工作

要求：
- 每个步骤给出具体的命令，告诉我在哪里运行（PowerShell 还是 Ubuntu 终端）
- 用简单易懂的语言解释每个命令的作用
- 如果我遇到错误，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步

现在开始第一步吧。
```

#### 方案 B：Windows 原生终端

> 适合：不想装 WSL，直接在 Windows 上开发

```
你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 Windows 系统，需要你一步一步指导我在 Windows 原生环境下搭建开发环境（不使用 WSL）。

请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：

1. 安装 Windows Terminal（如果还没有）
2. 安装 Node.js（通过官网安装包或 winget）
3. 安装 Git for Windows
4. 安装 Python
5. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选
6. 配置 Git 用户信息
7. 安装代码编辑器（VS Code）
8. 验证所有工具是否正常工作

要求：
- 每个步骤给出具体的命令或操作步骤
- 用简单易懂的语言解释每个步骤的作用
- 如果我遇到错误，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步

现在开始第一步吧。
```

---

### 🍎 macOS 用户提示词

```
你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 macOS 系统，需要你一步一步指导我从零搭建 Vibe Coding 开发环境。

请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：

1. 安装 Homebrew 包管理器
2. 使用 Homebrew 安装 Node.js
3. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选
4. 安装基础开发工具（git, python, tmux）
5. 配置 Git 用户信息
6. 安装代码编辑器（VS Code 或 Neovim）
7. 验证所有工具是否正常工作

要求：
- 每个步骤给出具体的命令
- 用简单易懂的语言解释每个命令的作用
- 如果我遇到错误，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步

现在开始第一步吧。
```

---

### 🐧 Linux 用户提示词

```
你是一个耐心的开发环境配置助手。我是一个完全的新手，使用 Linux 系统（Ubuntu/Debian），需要你一步一步指导我从零搭建 Vibe Coding 开发环境。

请按以下顺序指导我，每次只给我一个步骤，等我确认完成后再进行下一步：

1. 更新系统并安装基础依赖（curl, build-essential）
2. 安装 nvm 和 Node.js
3. 安装 Codex CLI（默认 AI CLI）；如无法使用，再安装 OpenCode CLI 作为备选
4. 安装开发工具（git, python, tmux）
5. 配置 Git 用户信息
6. 安装代码编辑器（VS Code 或 Neovim）
7. 验证所有工具是否正常工作

要求：
- 每个步骤给出具体的命令
- 用简单易懂的语言解释每个命令的作用
- 如果我遇到错误，帮我分析原因并给出解决方案
- 每完成一步，问我是否成功，然后再继续下一步

现在开始第一步吧。
```

---

### 配置完成后

#### IDE 配置

开发环境装好后，再选择编辑器。新手默认选 VS Code；想使用 AI 原生 IDE 时，再考虑 Cursor 或 Windsurf。

如果你不知道该选 VS Code、Cursor 还是 Windsurf，先打开网页版 AI，把下面提示词和本节内容一起复制进去：

```text
你是一个面向零基础用户的 IDE 配置助手。

请根据我的电脑环境和目标，帮我选择合适的 IDE 路线，并输出逐步执行流程。

我的当前情况是：
- 操作系统：[填写 Windows 11 / WSL2 / macOS / Linux]
- 是否已经安装 VS Code / Cursor / Windsurf：[填写没有 / 已安装某个]
- 是否已经完成开发环境搭建：[填写是 / 否 / 不确定]
- 当前目标：[填写我想用 IDE 做什么项目或任务]
- 卡住的位置：[如果已经卡住，填写具体问题；如果没有，写“还没开始”]

要求：
1. 每一步只做一件事。
2. 每一步都说明我要点哪里、输入什么、观察什么、如何判断成功。
3. 如果涉及命令行操作，每条命令都必须单独放在代码块里。
4. 不要跳步；默认我是第一次配置新电脑。
5. 如果我后续贴报错或截图描述，请根据当前步骤给出最小修复方案。
```

##### VS Code（默认推荐）

适合：免费、通用、教程最多，Windows + WSL 体验稳定。

Windows + WSL 用户重点做：

1. 在 Windows 上安装 VS Code。
2. 安装 **Remote - WSL** 扩展。
3. 从 Ubuntu 终端进入项目目录，执行 `code .` 打开项目。
4. 安装基础扩展：GitLens、Prettier、ESLint、Local History。
5. 确认 VS Code 终端默认进入 WSL 环境。

macOS / Linux / Windows 原生用户重点做：

1. 安装 VS Code。
2. 安装基础扩展：GitLens、Prettier、ESLint、Local History。
3. 配置自动保存和格式化。
4. 确认终端、Git、Node.js、Python 可用。

##### Cursor

适合：想要 AI 原生 IDE，且愿意使用 Cursor 的内置 AI 编程能力。

配置重点：

1. 从 [cursor.com](https://cursor.com) 下载并安装。
2. 首次启动后登录账号。
3. 如已有 VS Code，可导入设置和扩展。
4. 熟悉核心入口：`Cmd/Ctrl + K`、`Cmd/Ctrl + L`、`Cmd/Ctrl + I`。
5. 打开项目后，先让 AI 读取 README、AGENTS 和当前目录结构，再执行任务。

##### Windsurf

适合：想体验另一类 AI 原生 IDE，或需要备用 IDE。

配置重点：

1. 从 [windsurf.com](https://windsurf.com) 下载并安装。
2. 注册并登录账号。
3. 打开项目目录。
4. 了解 Cascade 等 AI 功能。
5. 用一个小修改验证 AI、终端和 Git 是否能正常工作。

#### CLI 工具配置技巧

AI CLI 工具默认会询问确认，开启全权限模式可以跳过：

```bash
# Codex - 默认推荐
codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh"

# Codex - 高权限模式，仅限可信仓库
codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox

# Claude Code - 跳过所有确认
claude --dangerously-skip-permissions

# OpenCode - 备选方案
opencode
```

#### 推荐的 Bash 别名配置

在 `~/.bashrc` 中添加以下配置，一个字母启动 AI：

```bash
# c - Codex 默认模式
alias c='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh"'

# cy - Codex 高权限模式，仅限可信仓库
alias cy='codex --search -m gpt-5.5 -c model_reasoning_effort="xhigh" --dangerously-bypass-approvals-and-sandbox'

# cc - Claude Code (全权限)
alias cc='claude --dangerously-skip-permissions'

# oc - OpenCode 备选方案
alias oc='opencode'
```

配置后执行 `source ~/.bashrc` 生效。

---

环境搭建完成后，继续下一步：

→ [CLI 配置](cli-setup.md) - 配置默认 AI CLI