166 lines
3.9 KiB
Markdown
166 lines
3.9 KiB
Markdown
|
# 静态部署指南
|
|||
|
|
|
|||
|
|
## 🚀 静态打包命令
|
|||
|
|
|
|||
|
|
### 构建静态文件
|
|||
|
|
```bash
|
|||
|
|
npm run build:static
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 本地预览静态网站
|
|||
|
|
```bash
|
|||
|
|
npm run preview
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 仅构建（不启动服务器）
|
|||
|
|
```bash
|
|||
|
|
npm run build
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 仅启动静态文件服务器
|
|||
|
|
```bash
|
|||
|
|
npm run serve
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 📁 输出目录
|
|||
|
|
|
|||
|
|
静态文件将生成在 `out/` 目录中，包含：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
out/
|
|||
|
|
├── index.html # 首页 (简体中文)
|
|||
|
|
├── zh-TW/
|
|||
|
|
│ ├── index.html # 繁体中文首页
|
|||
|
|
│ ├── about/index.html # 关于我们页面
|
|||
|
|
│ ├── products/index.html # 产品页面
|
|||
|
|
│ ├── news/
|
|||
|
|
│ │ ├── index.html # 新闻列表
|
|||
|
|
│ │ └── [id]/index.html # 新闻详情
|
|||
|
|
│ └── support/index.html # 支持页面
|
|||
|
|
├── en/
|
|||
|
|
│ ├── index.html # 英文首页
|
|||
|
|
│ └── ... # 其他英文页面
|
|||
|
|
├── news/
|
|||
|
|
│ ├── index.html # 默认语言新闻列表
|
|||
|
|
│ └── [id]/index.html # 默认语言新闻详情
|
|||
|
|
├── about/index.html # 默认语言关于页面
|
|||
|
|
├── products/index.html # 默认语言产品页面
|
|||
|
|
├── support/index.html # 默认语言支持页面
|
|||
|
|
└── _next/ # Next.js 静态资源
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🌐 部署到不同平台
|
|||
|
|
|
|||
|
|
### 1. Netlify
|
|||
|
|
1. 将 `out/` 目录拖拽到 Netlify 控制台
|
|||
|
|
2. 或连接 Git 仓库，设置构建命令：
|
|||
|
|
```
|
|||
|
|
Build command: npm run build:static
|
|||
|
|
Publish directory: out
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. Vercel
|
|||
|
|
```bash
|
|||
|
|
npx vercel --prod
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. GitHub Pages
|
|||
|
|
1. 将 `out/` 目录内容推送到 `gh-pages` 分支
|
|||
|
|
2. 在仓库设置中启用 GitHub Pages
|
|||
|
|
|
|||
|
|
### 4. 服务器部署
|
|||
|
|
将 `out/` 目录上传到服务器的网站根目录
|
|||
|
|
|
|||
|
|
## ⚙️ 配置说明
|
|||
|
|
|
|||
|
|
### 基础路径配置
|
|||
|
|
如果需要部署到子目录，修改 `next.config.mjs`：
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
const nextConfig = {
|
|||
|
|
output: 'export',
|
|||
|
|
basePath: '/your-subdirectory', // 取消注释并设置路径
|
|||
|
|
// ...
|
|||
|
|
};
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 图片优化
|
|||
|
|
静态导出中图片优化已设置为：
|
|||
|
|
```js
|
|||
|
|
images: {
|
|||
|
|
unoptimized: true, // 静态导出必需
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🔄 多语言路由说明
|
|||
|
|
|
|||
|
|
静态导出后的路由结构：
|
|||
|
|
|
|||
|
|
- **简体中文 (默认)**：`/`, `/about`, `/news/xxx`
|
|||
|
|
- **繁体中文**：`/zh-TW/`, `/zh-TW/about`, `/zh-TW/news/xxx`
|
|||
|
|
- **英文**：`/en/`, `/en/about`, `/en/news/xxx`
|
|||
|
|
|
|||
|
|
## ⚠️ 注意事项
|
|||
|
|
|
|||
|
|
### 静态导出限制
|
|||
|
|
1. **无服务器端渲染**：所有页面在构建时生成
|
|||
|
|
2. **无中间件**：语言切换依赖客户端逻辑
|
|||
|
|
3. **无动态API路由**：不能使用 `/api` 路由
|
|||
|
|
4. **无服务器端重定向**：依赖客户端跳转
|
|||
|
|
|
|||
|
|
### 语言切换机制
|
|||
|
|
在静态模式下：
|
|||
|
|
- 中间件不会执行
|
|||
|
|
- 语言切换完全依赖客户端 JavaScript
|
|||
|
|
- Cookie 设置在客户端进行
|
|||
|
|
|
|||
|
|
### 新增文章
|
|||
|
|
如需添加新文章，需要：
|
|||
|
|
1. 在 `docs/news/` 中添加 Markdown 文件
|
|||
|
|
2. 更新页面中的 `generateStaticParams` 函数
|
|||
|
|
3. 重新构建
|
|||
|
|
|
|||
|
|
## 🧪 测试
|
|||
|
|
|
|||
|
|
### 本地测试
|
|||
|
|
```bash
|
|||
|
|
# 构建并预览
|
|||
|
|
npm run preview
|
|||
|
|
|
|||
|
|
# 访问 http://localhost:3000
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 构建验证
|
|||
|
|
```bash
|
|||
|
|
# 检查构建输出
|
|||
|
|
npm run build:static
|
|||
|
|
ls -la out/
|
|||
|
|
|
|||
|
|
# 验证多语言页面
|
|||
|
|
ls -la out/zh-TW/
|
|||
|
|
ls -la out/en/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🔧 故障排除
|
|||
|
|
|
|||
|
|
### 常见问题
|
|||
|
|
|
|||
|
|
1. **页面404**：检查 `generateStaticParams` 是否包含所有路由
|
|||
|
|
2. **样式丢失**：确认 CSS 文件正确引入
|
|||
|
|
3. **图片不显示**：检查图片路径和 `unoptimized: true` 设置
|
|||
|
|
4. **语言切换无效**：确认 JavaScript 已启用
|
|||
|
|
|
|||
|
|
### 调试步骤
|
|||
|
|
1. 检查 `out/` 目录结构
|
|||
|
|
2. 查看浏览器开发者工具控制台
|
|||
|
|
3. 验证静态文件访问路径
|
|||
|
|
|
|||
|
|
## 📈 性能优化
|
|||
|
|
|
|||
|
|
- ✅ 自动代码分割
|
|||
|
|
- ✅ 静态资源优化
|
|||
|
|
- ✅ CSS 压缩
|
|||
|
|
- ✅ JavaScript 压缩
|
|||
|
|
- ✅ 预加载关键资源
|
|||
|
|
|
|||
|
|
静态导出的网站加载速度极快，适合 CDN 分发！
|