1. Next.js静态导出(SSG)完全指南作为一名长期使用Next.js的前端开发者我发现静态站点生成(SSG)是提升Web应用性能的利器。Next.js的静态导出功能让我们能够将动态应用转化为静态文件同时保留React的交互能力。这种混合渲染模式特别适合内容相对固定但需要快速加载的网站。2. 核心配置解析2.1 基础配置方法在next.config.js中启用静态导出只需要一个简单配置// next.config.js module.exports { output: export }这个配置会让next build命令生成静态文件到out目录。我建议同时设置distDir来改变输出目录名称避免与其他构建工具冲突// next.config.js module.exports { output: export, distDir: dist }2.2 路由处理技巧Next.js默认会为每个路由生成对应的HTML文件。对于动态路由我们需要使用generateStaticParams// app/blog/[slug]/page.js export async function generateStaticParams() { const posts await getPosts() return posts.map((post) ({ slug: post.slug })) }这个函数会在构建时运行为每个博客文章生成静态页面。我在实际项目中发现对于内容管理系统(CMS)集成的项目这个功能特别有用。3. 数据获取策略3.1 服务端数据获取在App Router中服务端组件的数据获取会自动在构建时执行// app/page.js export default async function Page() { const res await fetch(https://api.example.com/data) const data await res.json() return div{data.title}/div }这种写法看起来像在服务端运行但在静态导出模式下它实际上会在构建时执行一次然后将结果固化到HTML中。3.2 客户端数据补充对于需要动态更新的内容我们可以结合SWR或React Query// app/client-page.js use client import useSWR from swr export default function ClientPage() { const { data } useSWR(/api/latest, fetcher) return divLatest: {data?.title}/div }这种混合模式让我能够在保持静态站点优势的同时实现部分内容的动态更新。4. 图片优化方案4.1 自定义图片加载器静态导出模式下默认的图片优化器不可用但我们可以配置自定义加载器// next.config.js module.exports { output: export, images: { loader: custom, loaderFile: ./image-loader.js } }然后创建对应的加载器文件// image-loader.js export default function cloudinaryLoader({ src, width, quality }) { return https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || auto}${src} }4.2 本地图片处理对于本地图片我建议在构建时使用sharp进行优化npm install sharp然后在next.config.js中启用module.exports { output: export, images: { loader: custom, loaderFile: ./image-loader.js }, experimental: { optimizePackageImports: [sharp] } }5. 部署实战经验5.1 文件结构解析构建完成后你会得到类似这样的目录结构out/ ├── index.html ├── blog/ │ ├── post-1.html │ ├── post-2.html ├── _next/ │ ├── static/ │ └── chunks/5.2 Nginx配置示例这是我常用的Nginx配置模板server { listen 80; server_name example.com; root /var/www/out; location / { try_files $uri $uri.html $uri/ 404; } location /blog/ { rewrite ^/blog/(.*)$ /blog/$1.html break; } error_page 404 /404.html; location /404.html { internal; } }6. 常见问题排查6.1 动态功能报错静态导出不支持以下功能动态API路由非GET方法身份验证会话实时数据更新如果遇到相关错误检查是否意外使用了这些功能。6.2 路由问题我遇到过两个典型的路由问题动态路由未预生成 - 确保所有动态路由都有对应的generateStaticParams客户端导航失效 - 检查Link组件是否正确使用6.3 构建体积过大解决方法使用dynamic imports延迟加载组件启用代码分割分析bundle大小npm install next/bundle-analyzer然后在next.config.js中配置const withBundleAnalyzer require(next/bundle-analyzer)({ enabled: process.env.ANALYZE true }) module.exports withBundleAnalyzer({ output: export })7. 性能优化技巧7.1 预加载关键资源在根布局中添加// app/layout.js import { PreloadResources } from ./preload-resources export default function Layout({ children }) { return ( html head PreloadResources / /head body{children}/body /html ) }创建preload-resources.js// app/preload-resources.js export function PreloadResources() { return ( link relpreload href/fonts/inter.woff2 asfont typefont/woff2 crossOriginanonymous / link relpreload href/_next/static/css/main.css asstyle / / ) }7.2 缓存策略在静态服务器上设置长期缓存location /_next/static { expires 1y; add_header Cache-Control public, immutable; }8. 从传统SPA迁移8.1 逐步迁移策略先迁移静态页面然后处理动态路由最后处理需要客户端状态的组件8.2 状态管理方案对于需要持久化状态的场景我推荐使用URL查询参数本地存储(localStorage)状态管理库如Zustand// hooks/use-persisted-state.js use client import { useEffect, useState } from react export function usePersistedState(key, initialValue) { const [state, setState] useState(() { if (typeof window ! undefined) { const saved localStorage.getItem(key) return saved ! null ? JSON.parse(saved) : initialValue } return initialValue }) useEffect(() { localStorage.setItem(key, JSON.stringify(state)) }, [key, state]) return [state, setState] }9. 高级应用场景9.1 多语言站点实现结合next-intl库// middleware.js import createMiddleware from next-intl/middleware export default createMiddleware({ locales: [en, zh], defaultLocale: en }) export const config { matcher: [/, /(zh|en)/:path*] }9.2 混合渲染模式对于需要部分动态内容的页面可以这样处理// app/dynamic-page.js use client import dynamic from next/dynamic const DynamicComponent dynamic(() import(../components/Dynamic), { ssr: false }) export default function Page() { return ( div h1Static Content/h1 DynamicComponent / /div ) }10. 版本升级指南从旧版本迁移时注意v13.3.0开始弃用next exportv14.0.0完全移除了next export新的output: export配置更灵活升级步骤移除package.json中的next export脚本添加output: export配置检查是否使用了不支持的API测试构建结果11. 调试技巧11.1 构建时调试在package.json中添加{ scripts: { build:debug: NODE_DEBUGnext:* next build } }11.2 客户端错误追踪使用Sentry等工具// app/sentry.js import * as Sentry from sentry/nextjs Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 0.1 })12. 测试策略12.1 静态HTML测试使用Playwright进行端到端测试// tests/homepage.spec.js import { test, expect } from playwright/test test(homepage has title, async ({ page }) { await page.goto(/) await expect(page).toHaveTitle(/Home/) })12.2 构建验证测试添加构建验证脚本// scripts/verify-build.js const fs require(fs) const path require(path) const outDir path.join(__dirname, ../out) if (!fs.existsSync(outDir)) { console.error(Build directory not found) process.exit(1) } const requiredFiles [index.html, _next/static] for (const file of requiredFiles) { if (!fs.existsSync(path.join(outDir, file))) { console.error(Missing required file: ${file}) process.exit(1) } }13. 安全注意事项13.1 内容安全策略添加CSP头// next.config.js module.exports { output: export, headers: async () [ { source: /(.*), headers: [ { key: Content-Security-Policy, value: default-src self; script-src self unsafe-inline } ] } ] }13.2 敏感信息保护确保.env.local文件不被包含在构建结果中# .gitignore .env.local14. 监控与维护14.1 性能监控使用Web Vitals// app/web-vitals.js use client import { reportWebVitals } from next/web-vitals export function WebVitals() { useEffect(() { reportWebVitals(console.log) }, []) }14.2 构建通知设置构建成功通知# package.json { scripts: { build: next build node scripts/notify.js } }创建通知脚本// scripts/notify.js const { Webhook } require(discord-webhook-node) const hook new Webhook(process.env.DISCORD_WEBHOOK) hook.send(Build completed successfully)15. 扩展阅读建议深入了解React Server Components学习更高级的缓存策略探索边缘函数与静态站点的结合研究部分静态生成(Partial Static Generation)模式静态导出只是Next.js强大功能的冰山一角。随着项目复杂度增加你会发现更多可以优化的地方。每次构建后分析性能指标持续改进才能打造出真正高性能的Web应用。