Tootaio Studio 网站（Nuxt 4）

Tootaio Studio 的官方网站代码仓库，基于 Nuxt 4、@nuxt/content、@nuxt/ui 与 i18n 构建，采用 TypeScript 与 ESM 配置。项目默认使用 pnpm 进行依赖与脚本管理。

• 在线地址：https://tootaio.com
• 技术要点：内容与 UI 分离（YAML 内容 + JSON 翻译）、类型安全的内容加载、内置 SEO 与 CSP 头部策略

---

特性概览

• Nuxt 4 与 Vue 3 <script setup lang="ts">，全量 TypeScript 化
• @nuxt/content 管理结构化 YAML 内容，zod 校验 schema，类型安全
• @nuxt/ui 负责 UI 组件与样式，支持暗色模式与主题定制
• @nuxtjs/i18n 多语言（英文、简中），消息分包按需加载
• @nuxtjs/seo 统一 SEO 元信息配置（OG/Twitter/keywords）
• Nitro routeRules 内置严格 CSP、缓存与安全响应头
• 运行时配置集成 WhatsApp 咨询（公开变量）

---

快速开始

先决条件

• Node.js 18.20+ 或 20+
• pnpm 8+

安装依赖

pnpm i

安装后会自动执行 nuxt prepare（见 package.json:postinstall）。

配置环境变量

cp .env.example .env

必须设置：

• NUXT_PUBLIC_WHATSAPP_NUMBER：用于页面内“立刻咨询”按钮，走 WhatsApp H5 链接。

注：nuxt.config.ts 提供默认占位值，生产环境应以 .env 覆盖。

本地开发

pnpm dev

访问 http://localhost:3000，支持热更新（HMR）与暗色模式切换。

---

常用脚本

• 开发：pnpm dev
• 构建：pnpm build（产物在 .output/）
• 预览：pnpm preview（以生产模式本地运行）
• 静态生成：pnpm generate（SSG 场景）
• 代码检查：pnpm exec eslint .

---

目录结构

• app/：Nuxt 应用源码
  • pages/：页面组件（如 app/pages/index.vue, app/pages/webDev.vue）
  • layouts/：布局（默认头部含语言与主题切换）
  • assets/css/main.css：主题与样式（集成 @nuxt/ui 与 tailwindcss）
  • composables/：组合式函数（如 LocalizedCollection.ts, NavLinks.ts）
  • schemas/：zod 定义（如 pricingPlanSchema.ts, buttonSchema.ts）
• content/：YAML 内容（按语言区分 en-US/, zh-CN/）
• i18n/locales/<locale>/：UI 文案 JSON 包（按页面拆分，如 common.json, index.json）
• public/：静态资源（如 favicon.ico, og-image-1.png, _robots.txt）
• 根配置：nuxt.config.ts, content.config.ts, eslint.config.mjs
• 文档：docs/（工程审计、路线等）

---

内容与多语言

内容模型（@nuxt/content）

项目在 content.config.ts 中用 zod 定义了页面内容的 schema，并建立集合与源文件的对应关系：

• index_en ↔ content/en-US/index.yml
• index_zh ↔ content/zh-CN/index.yml
• webDev_en ↔ content/en-US/webDev.yml
• webDev_zh ↔ content/zh-CN/webDev.yml

在页面中通过类型安全的加载器获取内容：

// 示例：在页面/组件中获取本地化内容
const { data: page } = await useLocalizedCollection('index')

上述加载器会根据当前语言自动选择集合，并在缺失时回退到英文。

UI 文案（@nuxtjs/i18n）

• 语言：en（en-US）、zh-CN
• 加载策略：strategy: "no_prefix"
• 文案文件：i18n/locales/<locale>/*.json

示例 key：index.featuredProjects.viewDemo, common.button.submit。

新增页面或模块时，请同步维护中英文版本的 YAML 与 JSON，保持 key 一致。

---

UI 与主题

• 组件库：@nuxt/ui（UPage*, UHeader, UButton, UTabs, UModal 等）
• 主题：app/assets/css/main.css 中可定制字体与主色（项目默认霓虹红 --color-primary）
• 暗色模式：内置 UColorModeButton，图标与样式随模式自适应
• 图标：@iconify-json/mdi 与 skill-icons 系列（通过 UIcon 使用）

---

SEO 与安全

• SEO：@nuxtjs/seo 统一设置标题、描述、OG、Twitter 等元信息（见 nuxt.config.ts 中 DEFAULT_SEO）
• 站点地址：site.url = https://tootaio.com
• 安全头：在 routeRules 配置了 CSP、X-Content-Type-Options, Referrer-Policy 等；静态资源（/_nuxt/**）设置了长期缓存
• 图片白名单：img-src 允许 self 与 https://img.tootaio.com 与 data:

---

运行时配置与外部集成

• 环境变量：NUXT_PUBLIC_WHATSAPP_NUMBER（公开变量，用于发起 WhatsApp 咨询）
• 组合式函数：useWhatsAppMsgSender() 会根据该号码构造 WhatsApp H5 链接并 window.open
• 示例入口：app/components/webDev/ContactSalesModal.vue 在提交后拼接多语言消息并发起咨询

---

代码规范与校验

• 风格：TypeScript、2 空格缩进、ESM 配置、组合式函数使用 PascalCase
• ESLint：@nuxt/eslint 预设，配置见 eslint.config.mjs
• 手动检查：pnpm exec eslint .

---

测试（当前状态）

• 暂未配置自动化测试
• 建议：单测使用 Vitest，E2E 使用 Playwright
• 在此之前请进行本地验证：
  • pnpm dev 运行并切换语言
  • 校验 content/*.yml 是否符合 content.config.ts 中的 schema
  • pnpm build 与 pnpm preview 能否成功

---

提交与协作

• 提交规范：Conventional Commits（含 scope），如：feat(content): ..., refactor(ui): ...
• 分支命名：feat/<desc>、fix/<desc>
• PR 说明：改动目的 / 关联 Issue / UI 截图 / 测试步骤
• 内容改动请确保中英文同步更新（YAML 与 i18n JSON）

---

部署建议

• 服务器渲染（默认）：pnpm build 生成 .output/ 后按 Nuxt/Nitro 的 Node 运行方式部署
• 静态站点：pnpm generate 进行 SSG（请根据实际路由策略评估可行性）
• 常见平台：Vercel / Netlify / 任意 Node 主机（注意保留 routeRules 与响应头设置）

---

参考文件

• 配置：nuxt.config.ts:1、content.config.ts:1
• 页面：app/pages/index.vue:1、app/pages/webDev.vue:1
• 主题：app/assets/css/main.css:1
• 多语言：i18n/locales/en-US/common.json:1、i18n/locales/zh-CN/common.json:1
• 环境：.env.example:1（复制为 .env 并填写）

---

许可

如无单独说明，本仓库内容归 Tootaio Studio 所有。