小鱼开发
2b35a9ced0
- 新增 cover_avatar 积分类型和弹窗支持 - Modal 组件支持 maxHeight 属性 - 素材匹配增加 loading 状态（匹配中...） - 修复 Windows 视频预览：统一 handlePreview、preload=metadata、修复 Rust UNC 路径 - 修复进度条倒退问题 - 更新运营脚本 - 新增 Windows 11 开发环境搭建文档
4.8 KiB
4.8 KiB
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），逐行执行：
:: ========== 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，重新打开，再执行验证：
npm config get registry
cargo --version
三、方案 A：只跑前端（连测试环境后端）
1. 拉代码
git clone <你的仓库地址>
cd meijiaka-zy\tauri-app
2. 装依赖
npm ci
3. 启动
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
pip install uv
3. Docker Desktop
- 下载：https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe
- 安装：默认，装完重启电脑。
- 重启后打开 Docker Desktop，等左下角状态变绿。
4. 后端启动
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/字幕生成等），另开终端：
cd meijiaka-zy\python-api
make scheduler
:: 或：python -m app.scheduler.main
5. 前端启动（连本地后端）
cd meijiaka-zy\tauri-app
npm run tauri dev
前端 Vite 开发服务器会代理 API 请求到 localhost:8000。如果代理异常，检查 tauri-app/src/api/client.ts 中的 PYTHON_API_BASE_URL。
五、验证清单
全部装完后，在 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 已经装了 |