Files

lanyuanxiaoyao d6a77b2c6e 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 处理

2026-05-15 11:26:46 +08:00

2.7 KiB

Raw Blame History

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

2.7 KiB Raw Blame History Unescape Escape