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>
2.1 KiB
2.1 KiB
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）