小鱼开发
2b35a9ced0
- 新增 cover_avatar 积分类型和弹窗支持 - Modal 组件支持 maxHeight 属性 - 素材匹配增加 loading 状态（匹配中...） - 修复 Windows 视频预览：统一 handlePreview、preload=metadata、修复 Rust UNC 路径 - 修复进度条倒退问题 - 更新运营脚本 - 新增 Windows 11 开发环境搭建文档
193 lines
4.8 KiB
Markdown
193 lines
4.8 KiB
Markdown
# 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` 已经装了 |
|