企业官网建设流程全解析

新人入职第一周最痛苦的事：遇到问题不知道找谁问、不知道去哪看日志、不知道常见报错是什么原因。

我把团队常见的 debug 场景整理成一份"急救手册"，放在 steering 里。新人遇到问题时 AI 能直接给出排查路径，不用等老员工有空回复。

新人 debug 的典型困境

新人看到报错： "TypeError: Cannot read properties of undefined (reading 'map')" 内心活动： ├── 这个报错什么意思？（知道） ├── 发生在哪里？（看 stack trace...看不太懂） ├── 为什么数据是 undefined？（不知道） ├── 接口没返回？还是传参有问题？（不确定） ├── 去问谁？（老员工在开会） └── 等了 2 小时... 有了急救手册后： ├── AI 根据报错类型匹配排查路径 ├── "这类错误 90% 是接口返回数据为 null，请检查..." ├── 给出具体的检查步骤 └── 20 分钟自行解决

急救手册结构

# Debug 急救手册（steering 文件） ## 常见报错 → 排查路径 ### TypeError: Cannot read properties of undefined **最常见原因（按概率排序）：** 1. 接口返回的 data 为 null/undefined（60%） - 检查：Network 面板看接口响应 - 修复：加可选链 `data?.list?.map()` 2. 组件 mount 时异步数据还没回来（25%） - 检查：是否有 loading 状态判断 - 修复：加 `if (!data) return <Loading />` 3. 解构了不存在的字段（15%） - 检查：console.log 打印接口返回结构 - 修复：加默认值 `const { list = [] } = data || {}` ### 页面白屏（无报错） **排查步骤：** 1. 打开 Console 看有没有静默错误 2. 看 Network 有没有 HTML/JS 404 3. 检查路由配置是否正确（src/route/routes/） 4. 清浏览器缓存（可能加载了旧 JS） ### 接口 401/403 **含义：** - 401 = token 过期 → 重新登录 - 403 = 无权限 → 检查角色配置 **排查：** 1. Application → Cookie 里的 token 是否存在 2. 是否切换了品牌/环境但 token 没刷新 3. 找后端确认角色权限配置 ### 样式错乱（CSS 冲突） **常见原因：** 1. 没用 CSS Modules（`.less` 而非 `.m.less`）→ 全局污染 2. antd 组件样式被覆盖 → 检查是否有 `:global` 滥用 3. 组件库版本冲突 → 检查 node_modules 有没有多个 antd 版本

环境相关问题

### 本地 npm test 启动失败 **常见原因：** 1. node 版本不对 → `nvm use`（看 .nvmrc） 2. 依赖没装 → `npm install` 3. 端口 8009 被占用 → `lsof -i :8009` 或换端口 4. 环境变量缺失 → 检查 env/ 目录 ### 代理接口报 502/504 **含义：** 后端服务挂了或网关超时 **确认方法：** 1. 用 Postman 直接请求后端地址（绕过代理） 2. 问后端是不是在发版 3. 切换环境试试（test → poc） ### 构建成功但页面空白 **排查：** 1. publicPath 配置是否正确 2. nginx 转发规则是否匹配 hash 路由 3. dist/index.html 里的资源路径是否可访问

业务逻辑相关

### brandId 相关问题 项目是多品牌架构，很多接口需要 brandId header。 **如果接口返回空数据或 400：** 1. 检查请求 header 里有没有 X-Brand-Id 2. 检查当前选择的品牌是否正确 3. 确认这个接口是否需要 brandId（看后端文档） ### 权限按钮不显示 **排查：** 1. 确认当前账号角色配置了该权限 2. 检查权限 key 是否拼写正确（看 permissions/ 目录） 3. 确认 useAuth().hasPermission 返回值 4. 测试环境可能权限数据不全 → 让后端加

AI 如何使用这份手册

当新人问 AI 问题时：

新人："页面报错了 Cannot read properties of undefined" ↓ AI（有 steering 上下文）： "根据项目经验，这个错误最常见的原因是接口返回数据为 null。 请按以下步骤排查： 1. 打开 DevTools → Network，找到对应接口 2. 查看 Response，确认 data 字段是否有值 3. 如果 data 是 null，在代码中加可选链保护： data?.list?.map(...) 或加 loading 判断 4. 如果 data 有值但结构和预期不同，console.log 打印确认字段名"

新人不需要看文档、不需要等人回复，AI 直接给排查路径。

手册的维护策略

来源： ├── 每次新人问的问题 → 总结加进手册 ├── 线上 bug 的根因 → 提炼为"排查路径" ├── 团队 retro 中提到的"坑" → 记录下来 └── 随着项目演进持续更新 维护频率： ├── 新人入职时集中补充一波 ├── 每个迭代结束回顾一次 ├── 遇到新类型问题随时追加 └── 约每月更新 1-2 次

效果数据

指标 使用前 使用后 变化 ────────────── ────── ────── ──── 新人首周日均提问数 8-10 次 3-4 次 -60% 问题平均解决时间 2h 20min -83% 老员工被打断次数/天 4-5 次 1-2 次 -60% 新人首个需求完成时间 5 天 3 天 -40%

给团队维护手册的建议

Do： ├── 按"报错信息"组织，方便搜索 ├── 给出具体步骤（不是"去看看接口"而是"打开 Network 面板→找到 xxx 接口→看 Response"） ├── 标注概率（"60% 是因为 A，25% 是因为 B"） ├── 放在 steering 里让 AI 可以引用 └── 让新人参与维护（他们遇到问题最多） Don't： ├── 写成大而全的文档（太长没人看） ├── 只写原因不写步骤（新人不知道怎么操作） ├── 一次写完不再更新（会过时） └── 放在飞书文档里（AI 无法引用）

💬 你们团队是怎么帮新人快速上手 debug 的？有类似的知识沉淀吗？

🔗完整 Skills 源码已开源：github.com/sleepyccat/ai-native-workflow，欢迎 Star ⭐ 和 PR。