lanyuanxiaoyao
763d814543
建立 docs/user/ 和 docs/development/ 分层文档结构： - docs/README.md 文档总路由、归属矩阵、影响分析规则 - docs/user/ 模板使用、配置、部署、故障排查 - docs/development/ 架构、后端、前端、构建发布开发规范 - README.md 轻量化为项目入口和索引 - 删除 DEVELOPMENT.md，内容拆分至专题文档 - 更新 openspec/config.yaml 首读入口和文档影响分析规则 - 修正 docs/prompts/README.md 过时引用和边界说明
62 lines
1.6 KiB
Markdown
62 lines
1.6 KiB
Markdown
# 故障排查
|
|
|
|
本文档记录使用模板时的常见问题和排查入口。
|
|
|
|
## 配置校验失败
|
|
|
|
启动时会校验 YAML 配置。未知字段会导致启动失败。
|
|
|
|
排查顺序：
|
|
|
|
1. 在 YAML 顶部添加 `# yaml-language-server: $schema=./config.schema.json`。
|
|
2. 对照 [配置文件](config.md) 检查配置结构。
|
|
3. 运行 `bun run schema:check` 确认 JSON Schema 是否同步。
|
|
|
|
## 变量无法解析
|
|
|
|
变量解析优先级为 variables 字段 > process.env > 默认值。如果三者均不存在，配置校验会失败。
|
|
|
|
常见修复：
|
|
|
|
```text
|
|
环境变量未设置 设置环境变量或在 variables 中声明
|
|
希望允许空值 使用 ${KEY|}
|
|
希望提供默认值 使用 ${KEY|default}
|
|
希望输出字面量 使用 $${KEY}
|
|
```
|
|
|
|
## 端口被占用
|
|
|
|
修改 config.yaml 中的 server.listen.port 字段为可用端口。
|
|
|
|
## Schema 不同步
|
|
|
|
config.schema.json 与 TypeBox 定义不一致时会导致校验行为异常。
|
|
|
|
```bash
|
|
bun run schema # 重新生成 config.schema.json
|
|
bun run schema:check # 校验是否同步
|
|
```
|
|
|
|
## 构建失败
|
|
|
|
先运行完整质量检查定位问题：
|
|
|
|
```bash
|
|
bun run check # schema:check + typecheck + lint + test
|
|
```
|
|
|
|
如果 check 通过但仍构建失败：
|
|
|
|
```bash
|
|
bun run verify # check + build 完整验证
|
|
```
|
|
|
|
检查 TypeScript 类型错误和构建脚本输出，确保所有依赖已安装（`bun install`）。
|
|
|
|
## 前端页面空白
|
|
|
|
- 确认后端 API server 已启动
|
|
- 开发模式下确认 Vite dev server 代理配置正确
|
|
- 生产模式下确认前端静态资源已正确嵌入可执行文件
|