docs: 开发文档面向AI精简重构，补充文档编撰规范
This commit is contained in:
@@ -1,106 +1,60 @@
|
||||
# 构建与发布
|
||||
|
||||
本文档说明开发服务、前后端集成、生产构建、脚本维护和环境变量。
|
||||
## 开发运行
|
||||
|
||||
适用场景：修改 scripts/、构建流程、静态资源集成或环境变量。
|
||||
- `bun run dev config.yaml` — 双进程（Bun API server --watch + Vite dev server HMR）
|
||||
- `bun run dev:server config.yaml` — 仅后端
|
||||
- `bun run dev:web` — 仅前端
|
||||
|
||||
## 开发期运行
|
||||
|
||||
```bash
|
||||
bun run dev config.yaml
|
||||
```
|
||||
|
||||
scripts/dev.ts 同时启动两个进程：
|
||||
|
||||
| 进程 | 用途 |
|
||||
| --------------- | --------------------------------------- |
|
||||
| Bun API server | 后端 API 服务，--watch 监听变更自动重启 |
|
||||
| Vite dev server | 前端 SPA、HMR 热更新 |
|
||||
|
||||
也可以单独启动：
|
||||
|
||||
```bash
|
||||
bun run dev:server config.yaml # 仅启动后端 API server
|
||||
bun run dev:web # 仅启动 Vite dev server
|
||||
```
|
||||
开发模式 Vite proxy 将 /api/\* 转发到 Bun。
|
||||
|
||||
## 前后端集成
|
||||
|
||||
开发模式下，Vite 通过 proxy 将 /api/\* 转发到 Bun。
|
||||
生产模式：Vite 构建为静态资源 → `import with { type: "file" }` 嵌入 Bun 可执行文件 → 非 API 路径 fetch fallback 处理。
|
||||
|
||||
生产模式下，前端通过 Vite 构建为静态资源，通过 import with { type: "file" } 嵌入 Bun 可执行文件。非 API 路径由 fetch fallback 处理。
|
||||
|
||||
路由优先级：Bun routes 具体路径 > 通配符。/api/meta 优先于 /api/\*。
|
||||
路由优先级：Bun routes 具体路径 > 通配符。`/api/meta` 优先于 `/api/*`。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
`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/`
|
||||
|
||||
```text
|
||||
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` — 交叉编译目标平台。
|
||||
|
||||
构建参数：
|
||||
## 脚本
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
| ------------------------- | ---------------- |
|
||||
| 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）。
|
||||
|
||||
| 脚本 | 文件 | 说明 |
|
||||
| --------------------- | --------------------------------- | ------------------------------ |
|
||||
| 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 | 显式设置版本号 |
|
||||
| bun test | (Bun 内置) | 运行全部测试 |
|
||||
## 配置文件
|
||||
|
||||
内部辅助脚本（不直接对外开放）：
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ----------------------------------- | ---------------------------------------------- |
|
||||
| scripts/bump-version-logic.ts | 版本号升迁/设置的逻辑实现 |
|
||||
| scripts/generate-migrations-data.ts | 构建时将 drizzle/\*.sql 嵌入为 TypeScript 模块 |
|
||||
|
||||
## 项目配置文件
|
||||
|
||||
| 文件 | 用途 |
|
||||
| -------------------- | --------------------------- |
|
||||
| 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 配置 |
|
||||
| drizzle.config.ts | Drizzle ORM 配置 |
|
||||
|
||||
## 验证期望
|
||||
|
||||
| 变更类型 | 验证方式 |
|
||||
| ---------------- | -------------------- |
|
||||
| 构建脚本 | bun run verify |
|
||||
| 静态资源集成 | bun run build |
|
||||
| 配置 schema 同步 | bun run schema:check |
|
||||
| 发布前完整验证 | bun run verify |
|
||||
| 文件 | 用途 |
|
||||
| -------------------- | -------------------- |
|
||||
| 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 配置 |
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
|
||||
Reference in New Issue
Block a user