lanyuanxiaoyao
34071a421a
将项目从模板标识 my-app 全部替换为产品标识 Alfred·阿福， 去掉所有模板措辞，文档语态转为产品视角。 核心标识替换： - name: my-app → alfred - title: My App → Alfred·阿福 - subtitle: Bun 全栈应用 → 智能信息处理中枢 - description: 全栈开发框架 → 基于 AI 的信息综合处理平台 - 日志路径: my-app.log → alfred.log - 构建产物: dist/my-app → dist/alfred（由 APP.name 自动适配） 文档更新： - README.md 重写为产品介绍 - docs/README.md 去掉模板段落 - docs/user/ 从模板使用指南改为产品手册 - docs/development/ 标识替换 + 去模板措辞 - openspec/config.yaml 去模板项目描述 - LICENSE 填入 Copyright 2025 lanyuanxiaoyao
1.6 KiB
1.6 KiB
故障排查
本文档记录使用 Alfred·阿福时的常见问题和排查入口。
配置校验失败
启动时会校验 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 代理配置正确
- 生产模式下确认前端静态资源已正确嵌入可执行文件