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:
58
openspec/specs/static-asset-embedding/spec.md
Normal file
58
openspec/specs/static-asset-embedding/spec.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Static Asset Embedding
|
||||
|
||||
定义构建时将 Vite 产出的前端静态资源嵌入 Bun 可执行文件的 code generation 流程和运行时静态资源服务逻辑。
|
||||
|
||||
## Purpose
|
||||
|
||||
支持将 Vite 构建的前端资源通过 `import with { type: "file" }` 嵌入 Bun 可执行文件,实现单文件交付的同时保持正确的缓存策略和 Content-Type 处理。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 构建时资源扫描与 Code Generation
|
||||
构建脚本 SHALL 在 Vite build 完成后扫描 `dist/web/` 目录,自动生成 TypeScript 文件,为每个静态资源创建 `import ... with { type: "file" }` 声明。
|
||||
|
||||
#### Scenario: 生成资源导入文件
|
||||
- **WHEN** 构建脚本扫描 `dist/web/` 目录
|
||||
- **THEN** 系统 SHALL 在 `.build/static-assets.ts` 中为每个文件生成 `import fN from "<path>" with { type: "file" }` 语句,并导出 `StaticAssets` 对象
|
||||
|
||||
#### Scenario: StaticAssets 对象结构
|
||||
- **WHEN** `static-assets.ts` 被生成
|
||||
- **THEN** 导出的对象 SHALL 包含 `indexHtml: Blob` 和 `files: Record<string, Blob>` 两个字段,其中 files 的 key 为 URL 路径(如 `/assets/index-a1b2c3.js`)
|
||||
|
||||
#### Scenario: 生成 production server entry
|
||||
- **WHEN** 构建脚本生成资源导入文件后
|
||||
- **THEN** 系统 SHALL 在 `.build/server-entry.ts` 中生成 production 入口,import bootstrap、config 和 staticAssets 并调用 bootstrap
|
||||
|
||||
### Requirement: 运行时静态资源服务
|
||||
系统 SHALL 提供 `serveStaticAsset` 函数,根据请求路径从 StaticAssets 中查找并返回对应资源。
|
||||
|
||||
#### Scenario: 请求根路径
|
||||
- **WHEN** 请求路径为 `/`
|
||||
- **THEN** 系统 SHALL 返回 `indexHtml`,Content-Type 为 `text/html; charset=utf-8`,Cache-Control 为 `no-cache`
|
||||
|
||||
#### Scenario: 请求已知静态资源
|
||||
- **WHEN** 请求路径匹配 `files` 中的某个 key
|
||||
- **THEN** 系统 SHALL 返回对应 Blob,Content-Type 根据文件扩展名推断,Cache-Control 为 `public, max-age=31536000, immutable`
|
||||
|
||||
#### Scenario: 请求未知带扩展名路径
|
||||
- **WHEN** 请求路径包含文件扩展名但未匹配任何已知资源
|
||||
- **THEN** 系统 SHALL 返回 404 响应
|
||||
|
||||
#### Scenario: SPA Fallback
|
||||
- **WHEN** 请求路径不包含文件扩展名且不以 `/api/` 开头
|
||||
- **THEN** 系统 SHALL 返回 `indexHtml`(SPA fallback)
|
||||
|
||||
### Requirement: Content-Type 推断
|
||||
系统 SHALL 根据文件扩展名推断正确的 Content-Type header。
|
||||
|
||||
#### Scenario: JavaScript 文件
|
||||
- **WHEN** 请求路径以 `.js` 或 `.mjs` 结尾
|
||||
- **THEN** Content-Type SHALL 为 `text/javascript; charset=utf-8`
|
||||
|
||||
#### Scenario: CSS 文件
|
||||
- **WHEN** 请求路径以 `.css` 结尾
|
||||
- **THEN** Content-Type SHALL 为 `text/css; charset=utf-8`
|
||||
|
||||
#### Scenario: SVG 文件
|
||||
- **WHEN** 请求路径以 `.svg` 结尾
|
||||
- **THEN** Content-Type SHALL 为 `image/svg+xml`
|
||||
Reference in New Issue
Block a user