feat: 迁移前端构建从 Bun fullstack 到 Vite
前端性能问题根因在于 Bun bundler 无法有效 code split、CSS
tree-shake 和产出优化的前端资源。经多轮 Bun 原生优化尝试
均无明显效果后，决定将前端构建迁回 Vite。
主要变更：
- 前端构建：从 Bun HTML import bundling 切换为 Vite build
（Rolldown code splitting、vendor chunk、CSS 优化）
- 开发模式：从 Bun fullstack 单进程 HMR 切换为 Vite dev
server + Bun API server 双进程（:5173 + :3000）
- 生产构建：三步流水线（Vite build → code generation →
Bun compile），通过 `import with { type: "file" }` 嵌入前端资源
- 静态资源服务：从 Bun HTML import manifest 切换为自定义
serveStaticAsset 函数，支持 SPA fallback 和正确的 Cache-Control
- Server 接口：BootstrapOptions 和 StartServerOptions 增加
staticAssets? 可选参数
- 文档更新：DEVELOPMENT.md 和 README.md 反映新的开发模式，
主 specs 同步 delta 变更
新增能力：
- static-asset-embedding: 构建时资源扫描与 code generation、
运行时静态资源服务
- vite-frontend-bundling: Vite 构建配置、code splitting 策略、
CSS 处理
This commit is contained in:
@@ -22,9 +22,9 @@ src/
|
||||
server/
|
||||
bootstrap.ts 后端统一启动引导（loadConfig → store → engine → startServer → shutdown）
|
||||
config.ts CLI 参数解析（仅提取配置文件路径）
|
||||
dev.ts 开发模式启动入口（mode: "development"，HMR 自动注入）
|
||||
dev.ts 开发模式启动入口（mode: "development"，仅 API server）
|
||||
main.ts 生产模式启动入口（mode: "production"，安全头启用）
|
||||
server.ts HTTP server 启动工厂（Bun.serve routes 声明式路由 + HTML import）
|
||||
server.ts HTTP server 启动工厂（Bun.serve routes 声明式路由 + fetch fallback 静态资源服务）
|
||||
helpers.ts 共享响应格式化工具（见下方函数清单）
|
||||
middleware.ts API 参数校验中间件（validateTargetId、validateTimeRange、validatePagination）
|
||||
routes/ API 路由 handler（按端点拆分）
|
||||
@@ -113,7 +113,7 @@ probe-config.schema.json 用户配置 JSON Schema 导出物（用于 IDE 自动
|
||||
HTTP 请求:
|
||||
Request → Bun.serve routes 声明式匹配 → routes/*.ts(handler)
|
||||
→ middleware.ts(参数校验) → helpers.ts(响应格式化) → Response
|
||||
前端: "/*": homepage (HTML import) → SPA fallback + HMR(开发模式)
|
||||
前端: fetch fallback → serveStaticAsset (生产) / Vite proxy (开发)
|
||||
```
|
||||
|
||||
### 1.2 库使用优先级
|
||||
@@ -748,44 +748,58 @@ export function TargetGroup({ name, targets, onTargetClick }: TargetGroupProps)
|
||||
bun run dev probes.yaml
|
||||
```
|
||||
|
||||
`bun --watch src/server/dev.ts` 启动单进程 fullstack 开发服务器：
|
||||
`scripts/dev.ts` 同时启动两个进程：
|
||||
|
||||
- 后端 API + 前端 SPA 在同一端口（默认 3000）
|
||||
- `development` 模式自动注入 HMR，前端修改即时热更新
|
||||
- `--watch` 监听后端文件变更自动重启
|
||||
- 访问 `http://127.0.0.1:3000` 即可使用完整应用
|
||||
- **Bun API server**（端口 3000）：后端 API 服务，`--watch` 监听后端文件变更自动重启
|
||||
- **Vite dev server**（端口 5173）：前端 SPA + HMR 热更新
|
||||
|
||||
开发时访问 `http://127.0.0.1:5173`，Vite 自动将 `/api` 和 `/health` 请求代理到后端。
|
||||
|
||||
也可以单独启动：
|
||||
|
||||
```bash
|
||||
bun run dev:server probes.yaml # 仅启动后端 API server
|
||||
bun run dev:web # 仅启动 Vite dev server
|
||||
```
|
||||
|
||||
### 3.2 前后端集成方式
|
||||
|
||||
#### 统一进程架构
|
||||
#### 双进程开发架构
|
||||
|
||||
前后端通过 Bun 的 HTML import 机制集成为单进程应用：
|
||||
开发模式下前后端分别由 Vite 和 Bun 服务：
|
||||
|
||||
- Vite dev server 负责前端 SPA、HMR、模块热替换
|
||||
- Bun API server 负责后端 API 路由
|
||||
- Vite 通过 proxy 配置将 `/api/*` 和 `/health` 转发到 Bun
|
||||
|
||||
#### 生产模式架构
|
||||
|
||||
生产模式下前端通过 Vite 构建为静态资源，通过 `import with { type: "file" }` 嵌入 Bun 可执行文件：
|
||||
|
||||
```typescript
|
||||
// server.ts
|
||||
import homepage from "../web/index.html";
|
||||
|
||||
const server = Bun.serve({
|
||||
development: mode === "development" ? { hmr: true, console: true } : false,
|
||||
fetch(req) {
|
||||
// staticAssets 存在时服务嵌入的前端资源
|
||||
return serveStaticAsset(new URL(req.url).pathname, staticAssets);
|
||||
},
|
||||
routes: {
|
||||
"/*": homepage, // SPA fallback（开发模式自动注入 HMR）
|
||||
"/api/*": () => ..., // API 通配符（未匹配路由返回 404）
|
||||
"/api/dashboard": { GET: (req) => handleDashboard(new URL(req.url), store, mode) },
|
||||
"/api/dashboard": { GET: (req) => handleDashboard(...) },
|
||||
"/health": { GET: () => handleHealth(mode) },
|
||||
// ...
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
- 开发模式（`development: { hmr: true, console: true }`）：Bun 自动为 HTML import 注入 HMR client，前端修改无需手动刷新，并将浏览器 console 回显到终端
|
||||
- 生产模式：HTML 及其引用的 JS/CSS 资源在 `bun build --compile` 时自动打包进可执行文件
|
||||
|
||||
#### 路由优先级
|
||||
|
||||
Bun routes 的匹配规则：具体路径 > 通配符。`/api/dashboard` 优先于 `/api/*`，`/health` 优先于 `/*`。
|
||||
|
||||
未匹配 method 的请求（如 POST /api/dashboard）会落入 `/api/*` 通配符返回 404。
|
||||
|
||||
非 API 路径由 fetch fallback 处理：有文件扩展名的返回对应静态资源或 404，无扩展名的返回 SPA index.html。
|
||||
|
||||
### 3.3 构建打包
|
||||
|
||||
#### 构建命令
|
||||
@@ -796,26 +810,25 @@ bun run build
|
||||
|
||||
#### 构建流程
|
||||
|
||||
`scripts/build.ts` 执行单步构建：
|
||||
`scripts/build.ts` 执行三步流水线：
|
||||
|
||||
```
|
||||
Bun.build({
|
||||
compile: { outfile: "dist/dial-server" },
|
||||
entrypoints: ["src/server/main.ts"],
|
||||
minify: true,
|
||||
sourcemap: "linked",
|
||||
})
|
||||
1. Vite build → dist/web/ (前端静态资源，含 code splitting)
|
||||
2. Code generation → .build/static-assets.ts + .build/server-entry.ts
|
||||
3. Bun compile → dist/dial-server (单可执行文件)
|
||||
```
|
||||
|
||||
- 入口为 `src/server/main.ts`（`mode: "production"`，启用安全头）
|
||||
- HTML import 的前端资源自动打包进可执行文件（Bun 自动生成 manifest）
|
||||
- 无需中间产物目录，一步生成最终 binary
|
||||
- Vite 构建前端资源到 `dist/web/`，自动 code splitting（vendor-react、vendor-tdesign、vendor-chart）
|
||||
- Code generation 扫描 `dist/web/` 生成 `import with { type: "file" }` 声明，将资源嵌入 binary
|
||||
- Bun compile 以 `.build/server-entry.ts` 为入口编译最终可执行文件
|
||||
- `.build/` 临时目录在构建完成后自动清理
|
||||
|
||||
#### 产物
|
||||
|
||||
| 产物 | 用途 |
|
||||
| ------------------ | ---------------------------------------- |
|
||||
| `dist/dial-server` | 生产可执行文件（含前端资源，单文件部署） |
|
||||
| `dist/web/` | Vite 构建的前端资源（构建中间产物） |
|
||||
|
||||
#### 构建参数
|
||||
|
||||
@@ -839,7 +852,7 @@ Bun.build({
|
||||
|
||||
```bash
|
||||
bun run clean
|
||||
# 清理 dist/ 构建产物和 *.bun-build 临时文件
|
||||
# 清理 dist/ 构建产物和 .build/ 临时文件
|
||||
```
|
||||
|
||||
### 3.4 开发工作流
|
||||
@@ -847,8 +860,9 @@ bun run clean
|
||||
#### 日常开发循环
|
||||
|
||||
```bash
|
||||
bun run dev probes.yaml # 启动开发环境（单进程，含 HMR）
|
||||
# 修改前端代码 → HMR 热更新 / 修改后端代码 → --watch 自动重启
|
||||
bun run dev probes.yaml # 启动双进程开发环境（Vite + API server）
|
||||
# 访问 http://127.0.0.1:5173
|
||||
# 修改前端代码 → Vite HMR 热更新 / 修改后端代码 → --watch 自动重启
|
||||
bun run check # 提交前运行完整质量检查
|
||||
```
|
||||
|
||||
@@ -863,17 +877,19 @@ bun run verify
|
||||
|
||||
### 3.5 Executable/E2E 验证
|
||||
|
||||
原 `scripts/smoke.ts` 覆盖过薄，已从当前工作流移除。后续如需验证 production executable 的 API、HTML import manifest、SPA fallback 和静态资源行为，应重新设计独立的 executable/E2E 测试。
|
||||
原 `scripts/smoke.ts` 覆盖过薄，已从当前工作流移除。后续如需验证 production executable 的 API、静态资源服务、SPA fallback 行为，应重新设计独立的 executable/E2E 测试。
|
||||
|
||||
### 3.6 脚本说明
|
||||
|
||||
| 脚本 | 文件 | 说明 |
|
||||
| ---------------------- | ----------------------------------- | ----------------------------------- |
|
||||
| `bun run dev` | `src/server/dev.ts` | 单进程 fullstack 开发服务（含 HMR） |
|
||||
| `bun run build` | `scripts/build.ts` | Bun 编译可执行文件（含前端资源） |
|
||||
| `bun run schema` | `scripts/generate-config-schema.ts` | 生成 `probe-config.schema.json` |
|
||||
| `bun run schema:check` | `scripts/generate-config-schema.ts` | 检查配置 schema 导出物是否同步 |
|
||||
| `bun run clean` | `scripts/clean.ts` | 清理构建缓存与临时文件 |
|
||||
| 脚本 | 文件 | 说明 |
|
||||
| ---------------------- | ----------------------------------- | ---------------------------------------- |
|
||||
| `bun run dev` | `scripts/dev.ts` | 双进程开发服务（Vite :5173 + API :3000） |
|
||||
| `bun run dev:server` | `src/server/dev.ts` | 仅启动后端 API server |
|
||||
| `bun run dev:web` | Vite CLI | 仅启动 Vite dev server |
|
||||
| `bun run build` | `scripts/build.ts` | Vite → codegen → Bun compile 三步构建 |
|
||||
| `bun run schema` | `scripts/generate-config-schema.ts` | 生成 `probe-config.schema.json` |
|
||||
| `bun run schema:check` | `scripts/generate-config-schema.ts` | 检查配置 schema 导出物是否同步 |
|
||||
| `bun run clean` | `scripts/clean.ts` | 清理构建缓存与临时文件 |
|
||||
|
||||
### 3.7 环境变量
|
||||
|
||||
|
||||
Reference in New Issue
Block a user