lanyuanxiaoyao
0d709c7681
- toImportSpecifier() 使用 replaceAll 替代 split(sep).join，明确 ESM import specifier 语义 - 增加 relativePath 可选参数支持测试注入 Windows relative 语义 - 重写 Windows 路径测试，使用 node:path.win32 显式模拟而非依赖当前平台 sep - 更新 DEVELOPMENT.md 记录构建 code generation 约定 - 同步 static-asset-embedding 和 windows-test-compat spec 新增要求
70 lines
3.6 KiB
Markdown
70 lines
3.6 KiB
Markdown
# 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`
|
||
|
||
### Requirement: 静态资源 import specifier SHALL 使用平台无关分隔符
|
||
构建时静态资源 code generation SHALL 将文件系统相对路径转换为 ESM import specifier，并确保生成的 import 路径在 Windows、macOS、Linux 开发环境下都使用 `/` 作为分隔符。
|
||
|
||
#### Scenario: Windows 相对路径转换为 import specifier
|
||
- **WHEN** code generation 将 Windows 文件系统相对路径 `..\\dist\\web\\assets\\app.js` 转换为静态资源 import specifier
|
||
- **THEN** 生成的 import specifier SHALL 为 `../dist/web/assets/app.js`，且 MUST NOT 包含 `\\`
|
||
|
||
#### Scenario: POSIX 相对路径保持 import specifier 形式
|
||
- **WHEN** code generation 将 POSIX 文件系统相对路径 `../dist/web/assets/app.js` 转换为静态资源 import specifier
|
||
- **THEN** 生成的 import specifier SHALL 保持为 `../dist/web/assets/app.js`
|