# 构建与发布

## 开发运行

- `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 配置     |

## 更新触发条件

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