ShaoHua
3213d4c718
- 重构架构：抽离AddCloudSyncServer到扩展类，补全中间层文档对齐 - 修复根路径404与鉴权跳转：新增中间件处理浏览器请求302跳转 - 实现种子数据初始化：添加默认管理员账号自动创建逻辑 - 优化前端代理与构建：新增Vite代理配置与自动构建Target - 补全测试与文档：新增集成测试，更新开发与部署文档
151 lines
5.3 KiB
Markdown
151 lines
5.3 KiB
Markdown
# 开发环境与构建
|
||
|
||
> 本文档面向开发者，介绍如何搭建开发环境、从源码构建和部署。
|
||
|
||
## 1. 开发环境搭建
|
||
|
||
### 1.1 前提要求
|
||
|
||
- .NET 10 SDK
|
||
- Node.js 18+
|
||
- Visual Studio 2022+（推荐）或 VS Code
|
||
- Inno Setup 6（仅 Windows 打包需要）
|
||
|
||
### 1.2 克隆与安装
|
||
|
||
```bash
|
||
git clone https://git.we965.cn/Tools/Hua.Todo.git
|
||
cd Hua.Todo
|
||
```
|
||
|
||
前端依赖安装：
|
||
|
||
```bash
|
||
cd src/Hua.Todo.Web
|
||
npm install
|
||
```
|
||
|
||
### 1.3 启动开发环境
|
||
|
||
#### 方式一：模式 B「Web 端双开」（推荐，调试 Host API + 前端）
|
||
|
||
> 模式 B = Hua.Todo.Host 同时承担「动态 API + 前端静态站点 + MCP」三大职责，
|
||
> 访问 `http://localhost:5173/` 即可看到完整 Todo 前端，HTTP 同源无需再配 Vite proxy。
|
||
|
||
开发调试时分两个终端（修改前端能 HMR 热更新，不会每次都触发 npm build）：
|
||
|
||
```powershell
|
||
# 终端 1：启动 Host（监听 :5173 HTTP + :7055 HTTPS，未登录时 HTTP 即可）
|
||
# ⚠️ 若尚未构建过前端，Host 直接启动后 GET / 返回 404。首次需要先 build 一次：
|
||
# cd src/Hua.Todo.Web && npm ci && npm run build
|
||
# 后续 build 会被 MSBuild Target 自动触发，见 1.4 节。
|
||
cd src/Hua.Todo.Host
|
||
dotnet run # 或 Visual Studio F5 调试 Hua.Todo.Host
|
||
```
|
||
|
||
```powershell
|
||
# 终端 2：Vite 开发服务器（:5174，负责前端 HMR；通过 .env.development 把 API 打回 :5173 Host）
|
||
cd src/Hua.Todo.Web
|
||
npm run dev
|
||
# 浏览器访问 http://localhost:5174 → 代码保存后浏览器立即刷新
|
||
```
|
||
|
||
> 关闭 Vite 后直接访问 `http://localhost:5173/` 也能看到上次构建的前端静态页（非 HMR）。
|
||
|
||
#### 方式二：模式 A「MAUI 嵌入模式」
|
||
|
||
在 Visual Studio 中直接调试运行 `Hua.Todo.Maui` 项目，MAUI 会自动启动内嵌 WebServer（`localhost:5057`）并加载前端。
|
||
云同步链路：前端同源调用 `:5057` → CloudSyncProxy → 用户配置的 Web 端地址（默认 `http://localhost:5173`）。
|
||
|
||
#### 方式三：纯 Host 发布模式（快速验证部署产物）
|
||
|
||
```powershell
|
||
# 单次构建（前端 dist + Host 二进制 + wwwroot 复制）
|
||
dotnet build src/Hua.Todo.Host -c Release
|
||
dotnet run -c Release --project src/Hua.Todo.Host
|
||
# 浏览器访问 http://localhost:5173/ → 与部署后的体验一致
|
||
```
|
||
|
||
### 1.4 BuildHuaTodoWebWebRoot 自动构建说明
|
||
|
||
`src/Hua.Todo.Host/Hua.Todo.Host.csproj` 内置 `BuildHuaTodoWebWebRoot` MSBuild Target（触发时机：`BeforeBuild`），每次 `dotnet build/publish Hua.Todo.Host` 时执行：
|
||
|
||
| 行为 | 说明 |
|
||
|---|---|
|
||
| 增量构建 | 仅当 `src/Hua.Todo.Web/package.json` 或 `src/**/*.{ts,vue,css,html}` 变化时才 npm build，否则跳过 |
|
||
| Node 缺失保护 | 未安装 Node/npm 时仅输出 Warning，不阻塞 Host C# API 层编译（CI 可在外层单独 build 前端） |
|
||
| 跳过开关 | `dotnet build /p:SkipBuildHuaTodoWebWebRoot=true` 禁用整个 Target |
|
||
| 双份拷贝 | 产物同时写入 `src/Hua.Todo.Host/wwwroot/`（本地 `dotnet run`）和 `bin/Release/net10.0/wwwroot/`（`dotnet publish` 打包） |
|
||
|
||
常见提示排查：
|
||
|
||
- **`[BuildHuaTodoWebWebRoot] 未检测到 Node/npm`**：安装 Node.js 18+ 并重启终端；或 CI 先 `cd src/Hua.Todo.Web && npm ci && npm run build`。
|
||
- **`[BuildHuaTodoWebWebRoot] npm run build 退出码 != 0`**：去 `src/Hua.Todo.Web` 手动 `npm run build` 看 TypeScript/Vite 报错，修复后再 build Host。
|
||
|
||
## 2. 版本构建 (Release Build)
|
||
|
||
### 2.1 脚本入口
|
||
|
||
位于根目录的 `publish.ps1` 系列脚本：
|
||
|
||
```powershell
|
||
# 全平台一键构建
|
||
.\publish.ps1 -Windows -Linux
|
||
|
||
# Windows 单独构建
|
||
.\publish-windows.ps1
|
||
|
||
# Linux 单独构建
|
||
.\publish-linux.ps1 -RuntimeIdentifier linux-x64 -SelfContained
|
||
```
|
||
|
||
### 2.2 产物输出位置
|
||
|
||
| 平台 | 路径 |
|
||
|---|---|
|
||
| Windows 安装包 | `artifacts\windows\win-x64\installer\` |
|
||
| Windows 绿色版 | `artifacts\windows\win-x64\publish\` |
|
||
| Linux | `artifacts\linux\linux-x64\`（`.tar.gz`） |
|
||
|
||
## 3. 服务端部署
|
||
|
||
### 3.0 构建流程（新增：前端 dist 自动进 wwwroot）
|
||
|
||
v1.3.0 起 `dotnet publish src/Hua.Todo.Host` 会自动执行：
|
||
1. `npm install`（仅 node_modules 不存在时）
|
||
2. `npm run build` → `src/Hua.Todo.Web/dist`
|
||
3. `dist/**/*` → `publish_output/wwwroot/`（保留目录结构）
|
||
|
||
因此部署前**不再需要**单独 build 前端，直接一条命令即可。CI 若在容器内无 Node，设置 `-p:SkipBuildHuaTodoWebWebRoot=true` 并在外层先 `npm ci && npm run build`。
|
||
|
||
### 3.1 Docker 部署（推荐）
|
||
|
||
```bash
|
||
docker build -t hua-todo-server -f src/Hua.Todo.Host/Dockerfile .
|
||
docker run -d \
|
||
--name hua-todo-server \
|
||
-p 5173:5173 \
|
||
-v /data/hua-todo/db:/app/data \
|
||
-e ASPNETCORE_ENVIRONMENT=Production \
|
||
hua-todo-server
|
||
```
|
||
|
||
### 3.2 直接部署
|
||
|
||
```bash
|
||
dotnet publish src/Hua.Todo.Host -c Release -o ./dist
|
||
# 将 ./dist 同步到服务器，可选配置 Systemd 服务
|
||
```
|
||
|
||
## 4. 数据库
|
||
|
||
- **开发/测试**：SQLite，路径 `src/Hua.Todo.Host/Hua.Todo.db`
|
||
- **生产**：SQLite（默认）或切换其他 EF Core 支持的数据库
|
||
- **迁移**：嵌入式宿主启动时自动执行 `db.Database.Migrate()`
|
||
|
||
## 5. 下一步
|
||
|
||
- 了解架构细节 → [07-技术架构设计](./07-技术架构设计.md)
|
||
- 了解云同步 → [08-云同步规则](./08-云同步规则.md)
|
||
- 编码规范 → [09-代码规范](./09-代码规范.md)
|