# Frontend 踩坑记录

## 2026-03-24

### 1. Naive UI 组件必须显式 import
- 问题：agent 重构页面时没有 import Naive UI 组件，页面样式全部丢失
- 原因：项目没有配置 Naive UI 自动导入，每个组件必须手动 import
- 解决：每个使用 Naive UI 的页面必须在 script setup 中 `import { NButton, NCard, ... } from 'naive-ui'`
- 检查方法：grep "from 'naive-ui'" 确认所有使用 Naive UI 的文件都有 import

### 2. useSEO 返回值必须用 reactive 包裹
- 问题：useSEO 返回的 computed ref 传给 PageHero 的 title prop 时，Vue 报 "Expected String, got Object"
- 原因：Vue 模板中对嵌套对象内的 computed ref 不会自动解包
- 解决：useSEO 返回 `reactive({ h1, title, description })`，不要返回普通对象包含 computed

### 3. usePublicApi 用 useFetch 而非 useAsyncData
- 问题：useAsyncData + $fetch 产生的是 _payload.json 请求，浏览器 Network 看不到 API 调用
- 解决：用 `useFetch('/api/content/[key]')` + `getCachedData: () => undefined` 确保客户端导航时真正请求 API
- 注意：_payload.json 是 Nuxt 路由机制，与数据接口共存是正常的

### 4. Naive UI 在 SSR 中会报 head 错误
- 问题：admin layout 用 NConfigProvider 包裹，SSR 阶段报 "Cannot read properties of undefined (reading 'head')"
- 解决：用 `<client-only>` 包裹整个 Naive UI 组件树，后台不需要 SSR/SEO
- 注意：不需要 @css-render/vue3-ssr 插件，直接删掉

### 5. 前台页面 v-if 防御性编程
- 问题：courses.vue 访问 `courses.instructors.placeholder` 时 instructors 不存在导致 500
- 解决：使用可选链 `courses.instructors?.placeholder || []`
- 教训：所有从 API 获取的数据字段访问都要用可选链，不能假设字段一定存在

### 6. summer-camp 数据源独立
- 问题：夏令营数据原来嵌套在 products.summerCamp 中，数据独立后前台页面要同步改
- 解决：usePublicApi('summer-camp') 替代 usePublicApi('products') + .summerCamp
- 同时：itinerary 从字符串数组归一化为对象数组后，模板渲染也要改（day.replace → day.title）