Alfred/docs/development/release.md

构建与发布

本文档说明开发服务、前后端集成、生产构建、脚本维护和环境变量。

适用场景：修改 scripts/、构建流程、静态资源集成或环境变量。

开发期运行

bun run dev config.yaml

scripts/dev.ts 同时启动两个进程：

进程	用途
Bun API server	后端 API 服务，--watch 监听变更自动重启
Vite dev server	前端 SPA、HMR 热更新

也可以单独启动：

bun run dev:server config.yaml  # 仅启动后端 API server
bun run dev:web                 # 仅启动 Vite dev server

前后端集成

开发模式下，Vite 通过 proxy 将 /api/* 转发到 Bun。

生产模式下，前端通过 Vite 构建为静态资源，通过 import with { type: "file" } 嵌入 Bun 可执行文件。非 API 路径由 fetch fallback 处理。

路由优先级：Bun routes 具体路径 > 通配符。/api/meta 优先于 /api/*。

构建

bun run build

构建流程：

1. Vite build      -> dist/web/
2. Code generation -> .build/static-assets.ts + .build/server-entry.ts
3. Bun compile     -> dist/my-app

构建参数：

环境变量	说明
BUN_TARGET / BUILD_TARGET	交叉编译目标平台

脚本说明

脚本	文件	说明
bun run dev	scripts/dev.ts	双进程开发服务
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	生成配置 JSON Schema
bun run schema:check	scripts/generate-config-schema.ts	检查配置 JSON Schema 同步
bun run clean	scripts/clean.ts	清理构建缓存与临时文件
bun run version:patch	scripts/bump-version.ts	升迁 patch 版本
bun run version:minor	scripts/bump-version.ts	升迁 minor 版本
bun run version:major	scripts/bump-version.ts	升迁 major 版本
bun run version:set	scripts/bump-version.ts	显式设置版本号

项目配置文件

文件	用途
package.json	项目信息、脚本、依赖声明
tsconfig.json	TypeScript 配置
eslint.config.js	ESLint 规则
commitlint.config.js	commitlint 提交信息格式校验
.prettierrc.json	Prettier 格式化规则
.lintstagedrc.json	lint-staged 配置
config.example.yaml	配置文件示例
config.schema.json	配置文件 JSON Schema
vite.config.ts	Vite 构建配置
bunfig.toml	Bun 配置

验证期望

变更类型	验证方式
构建脚本	bun run verify
静态资源集成	bun run build
配置 schema 同步	bun run schema:check
发布前完整验证	bun run verify

更新触发条件

修改开发服务、前后端集成、构建产物、脚本参数或验证方式时，必须更新本文档。