feat: 初始提交

docs/user/troubleshoot.md

@@ -0,0 +1,61 @@
+# 故障排查
+
+本文档记录使用模板时的常见问题和排查入口。
+
+## 配置校验失败
+
+启动时会校验 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 代理配置正确
+- 生产模式下确认前端静态资源已正确嵌入可执行文件