docs: overhaul README with detailed project guide
Replace the generic Nuxt starter README with comprehensive documentation specific to the Tootaio Studio website project. The new README provides a detailed guide for developers, covering: - Project features and technology stack (Nuxt 4, Content, UI, i18n). - Setup, installation, and environment configuration. - Directory structure and code organization. - Content management workflow using YAML and zod schemas. - i18n implementation for UI text. - UI components, theming, and dark mode. - SEO and security best practices (CSP, routeRules). - Contribution guidelines and deployment suggestions.
This commit is contained in:
214
README.md
214
README.md
@@ -1,75 +1,191 @@
|
|||||||
# Nuxt Minimal Starter
|
# Tootaio Studio 网站（Nuxt 4）
|
||||||
|
|
||||||
Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
|
Tootaio Studio 的官方网站代码仓库，基于 Nuxt 4、@nuxt/content、@nuxt/ui 与 i18n 构建，采用 TypeScript 与 ESM 配置。项目默认使用 pnpm 进行依赖与脚本管理。
|
||||||
|
|
||||||
## Setup
|
- 在线地址：`https://tootaio.com`
|
||||||
|
- 技术要点：内容与 UI 分离（YAML 内容 + JSON 翻译）、类型安全的内容加载、内置 SEO 与 CSP 头部策略
|
||||||
|
|
||||||
Make sure to install dependencies:
|
---
|
||||||
|
|
||||||
|
## 特性概览
|
||||||
|
|
||||||
|
- 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+
|
||||||
|
|
||||||
|
### 安装依赖
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# npm
|
pnpm i
|
||||||
npm install
|
|
||||||
|
|
||||||
# pnpm
|
|
||||||
pnpm install
|
|
||||||
|
|
||||||
# yarn
|
|
||||||
yarn install
|
|
||||||
|
|
||||||
# bun
|
|
||||||
bun install
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Development Server
|
安装后会自动执行 `nuxt prepare`（见 `package.json:postinstall`）。
|
||||||
|
|
||||||
Start the development server on `http://localhost:3000`:
|
### 配置环境变量
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# npm
|
cp .env.example .env
|
||||||
npm run dev
|
```
|
||||||
|
|
||||||
# pnpm
|
必须设置：
|
||||||
|
|
||||||
|
- `NUXT_PUBLIC_WHATSAPP_NUMBER`：用于页面内“立刻咨询”按钮，走 WhatsApp H5 链接。
|
||||||
|
|
||||||
|
注：`nuxt.config.ts` 提供默认占位值，生产环境应以 `.env` 覆盖。
|
||||||
|
|
||||||
|
### 本地开发
|
||||||
|
|
||||||
|
```bash
|
||||||
pnpm dev
|
pnpm dev
|
||||||
|
|
||||||
# yarn
|
|
||||||
yarn dev
|
|
||||||
|
|
||||||
# bun
|
|
||||||
bun run dev
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Production
|
访问 `http://localhost:3000`，支持热更新（HMR）与暗色模式切换。
|
||||||
|
|
||||||
Build the application for production:
|
---
|
||||||
|
|
||||||
```bash
|
## 常用脚本
|
||||||
# npm
|
|
||||||
npm run build
|
|
||||||
|
|
||||||
# pnpm
|
- 开发：`pnpm dev`
|
||||||
pnpm build
|
- 构建：`pnpm build`（产物在 `.output/`）
|
||||||
|
- 预览：`pnpm preview`（以生产模式本地运行）
|
||||||
|
- 静态生成：`pnpm generate`（SSG 场景）
|
||||||
|
- 代码检查：`pnpm exec eslint .`
|
||||||
|
|
||||||
# yarn
|
---
|
||||||
yarn build
|
|
||||||
|
|
||||||
# bun
|
## 目录结构
|
||||||
bun run build
|
|
||||||
|
- `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`
|
||||||
|
|
||||||
|
在页面中通过类型安全的加载器获取内容：
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// 示例：在页面/组件中获取本地化内容
|
||||||
|
const { data: page } = await useLocalizedCollection('index')
|
||||||
```
|
```
|
||||||
|
|
||||||
Locally preview production build:
|
上述加载器会根据当前语言自动选择集合，并在缺失时回退到英文。
|
||||||
|
|
||||||
```bash
|
### UI 文案（@nuxtjs/i18n）
|
||||||
# npm
|
|
||||||
npm run preview
|
|
||||||
|
|
||||||
# pnpm
|
- 语言：`en`（en-US）、`zh-CN`
|
||||||
pnpm preview
|
- 加载策略：`strategy: "no_prefix"`
|
||||||
|
- 文案文件：`i18n/locales/<locale>/*.json`
|
||||||
|
|
||||||
# yarn
|
示例 key：`index.featuredProjects.viewDemo`, `common.button.submit`。
|
||||||
yarn preview
|
|
||||||
|
|
||||||
# bun
|
新增页面或模块时，请同步维护中英文版本的 YAML 与 JSON，保持 key 一致。
|
||||||
bun run preview
|
|
||||||
```
|
|
||||||
|
|
||||||
Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
|
---
|
||||||
|
|
||||||
|
## 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 所有。
|
||||||
|
|||||||
Reference in New Issue
Block a user