Alfred/docs/development/release.md

构建与发布

开发运行

• bun run dev config.yaml — 双进程（Bun API server --watch + Vite dev server HMR）
• bun run dev:server config.yaml — 仅后端
• bun run dev:web — 仅前端

开发模式 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/migrations-data.ts + .build/server-entry.ts
3. Bun compile → dist/alfred
4. Cleanup → 清理 .build/

构建参数：BUN_TARGET / BUILD_TARGET — 交叉编译目标平台。

脚本

脚本	文件	说明
dev	scripts/dev.ts	双进程开发服务
dev:server	src/server/dev.ts	仅后端
dev:web	Vite CLI	仅前端
build	scripts/build.ts	Vite → codegen → compile
schema	scripts/generate-config-schema.ts	生成 JSON Schema
schema:check	(同上)	检查 Schema 同步
clean	scripts/clean.ts	清理构建缓存
version:patch/minor/major/set	scripts/bump-version.ts	版本升迁

内部辅助：scripts/bump-version-logic.ts（版本逻辑）、scripts/generate-migrations-data.ts（构建时嵌入 SQL）。

配置文件

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

更新触发条件

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