98 lines
3.9 KiB
Markdown
98 lines
3.9 KiB
Markdown
# 构建与发布
|
||
|
||
本文档说明开发服务、前后端集成、生产构建、脚本维护和环境变量。
|
||
|
||
适用场景：修改 scripts/、构建流程、静态资源集成或环境变量。
|
||
|
||
## 开发期运行
|
||
|
||
```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 构建为静态资源，通过 import with { type: "file" } 嵌入 Bun 可执行文件。非 API 路径由 fetch fallback 处理。
|
||
|
||
路由优先级：Bun routes 具体路径 > 通配符。/api/meta 优先于 /api/\*。
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
bun run build
|
||
```
|
||
|
||
构建流程：
|
||
|
||
```text
|
||
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 |
|
||
|
||
## 更新触发条件
|
||
|
||
修改开发服务、前后端集成、构建产物、脚本参数或验证方式时，必须更新本文档。
|