# Windows 11 开发环境搭建指南

> 适用场景：全新重装系统后的 Windows 11，国内网络环境。

---

## 前置说明

- **WebView2**：Windows 11 自带，无需安装。
- **WSL2**：Windows 11 默认支持，Docker Desktop 会自动启用。
- **全程使用 cmd + 官网 .exe 安装包**，不依赖 PowerShell 脚本。

---

## 一、基础工具安装（图形界面，双击下一步）

按顺序安装，装完一个再装下一个。

### 1. Git

- 下载：https://git-scm.com/download/win
- 安装：全默认，一路 Next。

### 2. Node.js 22 LTS

- 下载：https://nodejs.org/
- 安装：勾选 **"Automatically install necessary tools"**（会自动装 Python 2.7 等构建工具）。

### 3. Visual Studio Build Tools 2022

- 下载：https://aka.ms/vs/17/release/vs_BuildTools.exe
- 安装：只勾选 **"使用 C++ 的桌面开发"**（约 8GB），其他全取消。

### 4. Rust

- 下载：https://rustup.rs/ → 点击 `rustup-init.exe (64-bit)`
- 安装：选 **1) Proceed with default installation**（默认 MSVC 工具链）。

---

## 二、国内镜像配置（cmd 执行）

打开 **cmd（Win+R → cmd）**，逐行执行：

```cmd
:: ========== npm 镜像 ==========
npm config set registry https://registry.npmmirror.com

:: ========== Rust 镜像 ==========
mkdir "%USERPROFILE%\.cargo" 2>nul

echo [source.crates-io] > "%USERPROFILE%\.cargo\config.toml"
echo replace-with = 'ustc' >> "%USERPROFILE%\.cargo\config.toml"
echo [source.ustc] >> "%USERPROFILE%\.cargo\config.toml"
echo registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/" >> "%USERPROFILE%\.cargo\config.toml"

setx RUSTUP_UPDATE_ROOT https://mirrors.ustc.edu.cn/rust-static/rustup
setx RUSTUP_DIST_SERVER https://mirrors.ustc.edu.cn/rust-static

:: ========== Python 镜像（预留，方案 B 用到） ==========
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

echo 镜像配置完成，请关闭并重新打开 cmd
```

**执行完后，关闭 cmd，重新打开**，再执行验证：

```cmd
npm config get registry
cargo --version
```

---

## 三、方案 A：只跑前端（连测试环境后端）

### 1. 拉代码

```cmd
git clone <你的仓库地址>
cd meijiaka-zy\tauri-app
```

### 2. 装依赖

```cmd
npm ci
```

### 3. 启动

```cmd
npm run tauri dev
```

前端默认连接 `https://dev.tapi.meijiaka.cn/api/v1`，无需本地后端。

---

## 四、方案 B：前后端都本地跑

在方案 A 基础上继续。

### 1. Python 3.13

- 下载：https://www.python.org/ftp/python/3.13.0/python-3.13.0-amd64.exe
- 安装：**务必勾选 "Add python.exe to PATH"**，然后 Install Now。

### 2. 安装 uv

```cmd
pip install uv
```

### 3. Docker Desktop

- 下载：https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe
- 安装：默认，装完**重启电脑**。
- 重启后打开 Docker Desktop，等左下角状态变绿。

### 4. 后端启动

```cmd
cd meijiaka-zy\python-api

:: 安装依赖
uv pip install -e ".[dev]"

:: 复制环境变量
copy .env.example .env

:: 启动数据库
docker compose -f docker-compose.test.yml up -d db redis

:: 数据库迁移
alembic upgrade head

:: 启动 API（终端 1）
make run
:: 或：uvicorn app.main:app --reload --port 8000
```

如果需要异步调度器（脚本/TTS/字幕生成等），另开终端：

```cmd
cd meijiaka-zy\python-api
make scheduler
:: 或：python -m app.scheduler.main
```

### 5. 前端启动（连本地后端）

```cmd
cd meijiaka-zy\tauri-app
npm run tauri dev
```

前端 Vite 开发服务器会代理 API 请求到 `localhost:8000`。如果代理异常，检查 `tauri-app/src/api/client.ts` 中的 `PYTHON_API_BASE_URL`。

---

## 五、验证清单

全部装完后，在 cmd 里执行：

```cmd
git --version
node -v
npm -v
rustc --version
cargo --version
python --version
uv --version
docker --version
```

每个都要有版本号输出。

---

## 六、常见问题

| 现象 | 原因 | 解决 |
|------|------|------|
| `npm ci` 卡住 | 镜像没配好 | 检查 `npm config get registry` 是否为 `registry.npmmirror.com` |
| `cargo build` 卡住 | Rust 镜像没生效 | 关闭 cmd 重新打开，或检查 `%USERPROFILE%\.cargo\config.toml` |
| Tauri 编译报错 `link.exe not found` | VS Build Tools 没装 C++ 桌面开发 | 重装，确保勾选了该工作负载 |
| `tauri dev` 白屏 | 前端代理地址错误 | 检查 `client.ts` 里的 base URL |
| Docker 启动失败 | WSL2 未启用 | 控制面板 → 程序和功能 → 启用 Windows 功能 → 勾选 **适用于 Linux 的 Windows 子系统** |
| `python` 命令找不到 | 安装时没勾选 Add to PATH | 重装 Python，务必勾选 |
| `alembic` 命令找不到 | 没在虚拟环境里 | 确保在 `python-api` 目录下执行，`uv pip install` 已经装了 |