Hua.Todo/docs/manual/06-开发环境与构建.md

开发环境与构建

本文档面向开发者，介绍如何搭建开发环境、从源码构建和部署。

1. 开发环境搭建

1.1 前提要求

• .NET 10 SDK
• Node.js 18+
• Visual Studio 2022+（推荐）或 VS Code
• Inno Setup 6（仅 Windows 打包需要）

1.2 克隆与安装

git clone https://git.we965.cn/Tools/Hua.Todo.git
cd Hua.Todo

前端依赖安装：

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）：

# 终端 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

# 终端 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 发布模式（快速验证部署产物）

# 单次构建（前端 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 系列脚本：

# 全平台一键构建
.\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 部署（推荐）

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 直接部署

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-技术架构设计
• 了解云同步 → 08-云同步规则
• 编码规范 → 09-代码规范