ee078b61bc
- 后台全面引入 Naive UI 组件库，统一 UI 规范 - 前台 usePublicApi 切换到 API 调用（GET /api/content/[key]） - 前后台数据源统一（site_content 表） - 产品线统一管理（tour/camp/course 三套编辑器） - 产品数据归一化（itinerary/faq/pricing 格式统一） - 表单提交 API 改写入 submissions 表 - 新增 submissions 标记已读 API - site-content PUT 支持 upsert - 修复前台 bug（stories 路由冲突、占位符警告、selector breadcrumb） - 消除 PageHero 类型警告（useSEO reactive 修复） - 25 个前台页面全部 HTTP 200，展示效果不变 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
35 行
2.1 KiB
Markdown
35 行
2.1 KiB
Markdown
# 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）
|