Files

lanyuanxiaoyao 763d814543 docs: 引入分层文档体系，删除 DEVELOPMENT.md

建立 docs/user/ 和 docs/development/ 分层文档结构：
- docs/README.md 文档总路由、归属矩阵、影响分析规则
- docs/user/ 模板使用、配置、部署、故障排查
- docs/development/ 架构、后端、前端、构建发布开发规范
- README.md 轻量化为项目入口和索引
- 删除 DEVELOPMENT.md，内容拆分至专题文档
- 更新 openspec/config.yaml 首读入口和文档影响分析规则
- 修正 docs/prompts/README.md 过时引用和边界说明

2026-05-25 19:09:08 +08:00

1.6 KiB

Raw Blame History

故障排查

本文档记录使用模板时的常见问题和排查入口。

配置校验失败

启动时会校验 YAML 配置。未知字段会导致启动失败。

排查顺序：

在 YAML 顶部添加 # yaml-language-server: $schema=./config.schema.json。
对照配置文件检查配置结构。
运行 bun run schema:check 确认 JSON Schema 是否同步。

变量无法解析

变量解析优先级为 variables 字段 > process.env > 默认值。如果三者均不存在，配置校验会失败。

常见修复：

环境变量未设置  设置环境变量或在 variables 中声明
希望允许空值    使用 ${KEY|}
希望提供默认值  使用 ${KEY|default}
希望输出字面量  使用 $${KEY}

端口被占用

修改 config.yaml 中的 server.listen.port 字段为可用端口。

Schema 不同步

config.schema.json 与 TypeBox 定义不一致时会导致校验行为异常。

bun run schema        # 重新生成 config.schema.json
bun run schema:check  # 校验是否同步

构建失败

先运行完整质量检查定位问题：

bun run check   # schema:check + typecheck + lint + test

如果 check 通过但仍构建失败：

bun run verify  # check + build 完整验证

检查 TypeScript 类型错误和构建脚本输出，确保所有依赖已安装（bun install）。

前端页面空白

确认后端 API server 已启动
开发模式下确认 Vite dev server 代理配置正确
生产模式下确认前端静态资源已正确嵌入可执行文件

1.6 KiB Raw Blame History