HaoAws/STATIC_DEPLOYMENT.md

静态部署指南

🚀 静态打包命令

构建静态文件

npm run build:static

本地预览静态网站

npm run preview

仅构建（不启动服务器）

npm run build

仅启动静态文件服务器

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

npx vercel --prod

3. GitHub Pages

1. 将 out/ 目录内容推送到 gh-pages 分支
2. 在仓库设置中启用 GitHub Pages

4. 服务器部署

将 out/ 目录上传到服务器的网站根目录

⚙️ 配置说明

基础路径配置

如果需要部署到子目录，修改 next.config.mjs：

const nextConfig = {
    output: 'export',
    basePath: '/your-subdirectory',  // 取消注释并设置路径
    // ...
};

图片优化

静态导出中图片优化已设置为：

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. 重新构建

🧪 测试

本地测试

# 构建并预览
npm run preview

# 访问 http://localhost:3000

构建验证

# 检查构建输出
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 分发！