125 lines
3.8 KiB
Markdown
125 lines
3.8 KiB
Markdown
# Seven - 多语言官网（Next.js 15）
|
||
|
||
<p align="center">
|
||
<img src="app/favicon.ico" />
|
||
</p>
|
||
|
||
基于 Next.js 15、Tailwind CSS 和 shadcn/ui 搭建的多语言企业官网模板，内置中/英/日/韩/繁体语言路由，统一页头/页尾布局与 SEO 元数据管理。
|
||
|
||
## 技术栈
|
||
|
||
- Next.js 15（App Router）
|
||
- React 18
|
||
- Tailwind CSS
|
||
- shadcn/ui
|
||
|
||
## 目录结构（关键项）
|
||
|
||
```
|
||
app/
|
||
[lang]/
|
||
layout.tsx # 按语言生成 Metadata（需 await params）
|
||
page.tsx # 首页入口（需 await params）
|
||
products/page.tsx # 产品页（Client 组件）
|
||
solutions/page.tsx # 解决方案页（Client 组件）
|
||
contact/page.tsx # 联系我们（使用 PageLayout，表单仅在客户端渲染）
|
||
components/
|
||
PageLayout.tsx # 统一 TDK、Navbar、Footer 与内容容器
|
||
Navbar.tsx
|
||
Footer.tsx
|
||
TDK.tsx # 页面标题/描述/关键词
|
||
data/
|
||
content.ts # 站点通用文案（多语言）
|
||
pageContent.ts # 各页面文案（多语言）
|
||
```
|
||
|
||
## 快速开始（Windows PowerShell）
|
||
|
||
```powershell
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 本地开发（默认 http://localhost:3000）
|
||
npm run dev
|
||
|
||
# 生产构建
|
||
npm run build
|
||
|
||
# 本地预览生产构建
|
||
npm run start
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Node.js ≥ 18.17（推荐 LTS）
|
||
- npm ≥ 9（或使用 pnpm/bun 亦可）
|
||
|
||
## 多语言与路由
|
||
|
||
- 路由格式：`/[lang]/...`，其中 `lang ∈ { en, zh-CN, zh-TW, ko, ja }`
|
||
- 入口页静态参数：`app/[lang]/page.tsx` 中的 `generateStaticParams()`
|
||
- 元数据生成：`app/[lang]/layout.tsx` 中的 `generateMetadata()` 会根据语言返回对应 TDK
|
||
|
||
注意：Next.js 15 起，动态段的 `params` 在服务端为 Promise，必须 `await` 后再使用，例如：
|
||
|
||
```ts
|
||
export async function generateMetadata({ params }: { params: Promise<{ lang: string }> }) {
|
||
const { lang } = await params;
|
||
// ...
|
||
}
|
||
```
|
||
|
||
## SEO 与 TDK
|
||
|
||
- 统一在 `PageLayout` 内通过 `TDK` 组件注入 `title/description/keywords`
|
||
- `app/[lang]/layout.tsx` 中维护各语言默认元数据与 `alternates.languages`
|
||
|
||
## SSR/CSR 与 Hydration 注意事项
|
||
|
||
- 避免在 SSR 阶段使用不稳定输出（如 `Date.now()`、`Math.random()`）
|
||
- 对于仅在客户端可用的交互（如带自动填充的表单），采用“客户端渲染占位”策略：
|
||
- `contact/page.tsx` 中使用 `isClient` 状态在挂载后再渲染表单，避免浏览器扩展（如 LastPass）注入导致水合不一致
|
||
- 若你引入新的服务端函数，确保在使用 `params` 前执行 `await`
|
||
|
||
## 常见问题（FAQ）
|
||
|
||
- Hydration failed：
|
||
- 检查是否使用了未固定输出的变量；
|
||
- 检查是否有浏览器扩展注入 DOM（如密码管理器）；
|
||
- 对仅客户端渲染的复杂表单使用 `isClient` 保护渲染；
|
||
- 移除不必要的 `suppressHydrationWarning`，定位并修复根因。
|
||
|
||
- Route used `params.lang`. `params` should be awaited：
|
||
- Next.js 15 的动态 API 是异步的，请调整类型为 `Promise<...>` 并 `await`。
|
||
|
||
## 开发脚本
|
||
|
||
```powershell
|
||
# 代码检查（如已配置）
|
||
npm run lint
|
||
|
||
# Tailwind 即时开发（随 dev 一起运行）
|
||
npm run dev
|
||
```
|
||
|
||
## 部署
|
||
|
||
- 推荐部署到 Vercel：
|
||
- Framework: Next.js
|
||
- Build Command: `npm run build`
|
||
- Output: `.next`
|
||
- Node Version: 使用项目/平台默认 LTS
|
||
- 也可自托管：
|
||
- 运行 `npm run build && npm run start`
|
||
|
||
## 贡献与代码风格
|
||
|
||
- 变量/函数命名清晰完整，避免缩写
|
||
- 避免深层嵌套，使用早返回
|
||
- TypeScript 明确标注导出 API 的类型
|
||
- 不捕获且吞掉错误；错误需被有意义处理
|
||
|
||
## 许可证
|
||
|
||
本仓库以 MIT 协议开源。根据业务需要可自由修改与商用。
|