1
0

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:
2026-05-15 11:26:46 +08:00
parent 28e46b8431
commit d6a77b2c6e
18 changed files with 735 additions and 152 deletions

View File

@@ -1,22 +1,26 @@
## Purpose
定义将 Bun HTML import 前端资源与 Bun 后端打包为单个 standalone executable 的生产构建、运行配置和验证要求。
定义将 Vite 构建的前端资源通过 code generation 嵌入 Bun 后端打包为单个 standalone executable 的生产构建、运行配置和验证要求。
## Requirements
### Requirement: 生产构建顺序
生产构建 MUST 通过 Bun.build 的 HTML import 识别机制一步完成前端资源打包和后端编译
生产构建 MUST 通过三步流水线完成Vite 前端构建 → code generation → Bun compile
#### Scenario: 运行生产构建
- **WHEN** 开发者运行生产构建命令
- **THEN** 系统 MUST 调用 Bun.build自动识别 server 入口中的 HTML import 并完成前端 bundling 和后端编译
- **THEN** 系统 MUST 依次执行 Vite build、资源导入 code generation、Bun.build compile最终输出单可执行文件
#### Scenario: 前端 bundling 失败
- **WHEN** Bun.build 在处理 HTML import 中的前端资源时失败
- **THEN** 系统 MUST 停止生产构建,且不能输出 stale executable
#### Scenario: Vite 构建失败
- **WHEN** Vite build 步骤失败
- **THEN** 系统 MUST 停止后续步骤,不生成 code generation 文件或 executable
#### Scenario: Bun compile 失败
- **WHEN** Bun.build compile 步骤失败
- **THEN** 系统 MUST 清理 `.build/` 临时目录,不保留 stale executable
### Requirement: 单 executable 输出
生产构建 SHALL 输出一个 standalone executable其中包含 Bun 后端和通过 HTML import manifest 嵌入的前端资源。构建流程 SHALL 不再生成项目自定义中间产物目录,构建失败时 SHALL 不保留 stale executable
生产构建 SHALL 输出一个 standalone executable其中包含 Bun 后端和通过 `import with { type: "file" }` 嵌入的 Vite 前端产出
#### Scenario: 在目标机器运行 executable
- **WHEN** 生成的 executable 在兼容目标平台上运行
@@ -24,19 +28,22 @@
#### Scenario: 服务嵌入的前端
- **WHEN** executable 收到前端根路径请求
- **THEN** 它 SHALL 通过 Bun 内置的 HTML import manifest 机制服务前端资源,且不需要外部 `dist/` 目录
- **THEN** 它 SHALL 通过内嵌的 Vite 构建产出服务前端资源,且不需要外部 `dist/` 目录
#### Scenario: 服务嵌入 API 和页面
- **WHEN** 生成的 executable 启动,且浏览器打开前端根路径
- **THEN** 页面 SHALL 展示同一个 executable 进程中 `/api/summary``/api/targets` 返回的数据
#### Scenario: 构建成功不生成自定义中间产物
- **WHEN** 生产构建成功完成并输出 executable
- **THEN** 系统 SHALL 不生成 `.build/` 静态资源清单或 server entry 中间产物
### Requirement: 构建中间产物管理
构建流程 SHALL 使用 `.build/` 临时目录存放 code generation 产物,构建完成后清理。
#### Scenario: 构建失败时不保留 stale executable
- **WHEN** 生产构建在任意步骤失败
- **THEN** 系统 SHALL 不输出上一次构建遗留的 stale executable
#### Scenario: 构建成功后清理中间产物
- **WHEN** 生产构建成功完成并输出 executable
- **THEN** 系统 SHALL 删除 `.build/` 临时目录
#### Scenario: 构建失败时清理中间产物
- **WHEN** 生产构建在 Bun compile 步骤失败
- **THEN** 系统 SHALL 删除 `.build/` 临时目录和 stale executable
### Requirement: 外部运行时配置
executable MUST 将环境相关运行时配置保留在嵌入的前端和 server bundle 之外。