如何创建 Next.js 应用程序的静态导出
Next.js 支持以静态站点或单页应用程序(SPA)起步,之后可以选择升级以使用需要服务器的功能。
Next.js 支持以静态站点或单页应用程序(SPA)起步,之后可以选择升级以使用需要服务器的功能。
运行 next build 时,Next.js 会为每个路由生成一个 HTML 文件。通过将严格的 SPA 拆分为单独的 HTML 文件,Next.js 可以避免在客户端加载不必要的 JavaScript 代码,从而减小包体积并实现更快的页面加载。
由于 Next.js 支持这种静态导出,它可以部署和托管在任何能够提供 HTML/CSS/JS 静态资源的 Web 服务器上。
配置#
要启用静态导出,请更改 next.config.js 中的输出模式:
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
output: 'export',
// 可选:将链接 `/me` -> `/me/`,并将 `/me.html` -> `/me/index.html` 输出
// trailingSlash: true,
// 可选:阻止自动将 `/me` -> `/me/`,而是保留 `href`
// skipTrailingSlashRedirect: true,
// 可选:将输出目录 `out` -> `dist`
// distDir: 'dist',
}
module.exports = nextConfig运行 next build 后,Next.js 将创建一个 out 文件夹,其中包含应用程序的 HTML/CSS/JS 资源。
你可以利用 getStaticProps 和 getStaticPaths 为 pages 目录中的每个页面(或为动态路由生成更多页面)生成一个 HTML 文件。
支持的功能#
Next.js 的核心设计支持静态导出。
Server Components#
当你运行 next build 生成静态导出时,app 目录内使用的 Server Components 将在构建期间运行,类似于传统的静态站点生成。
生成的组件将被渲染为静态 HTML 用于初始页面加载,并生成静态 payload 用于路由间的客户端导航。使用静态导出时,你的 Server Components 无需更改,除非它们使用了动态服务器函数。
export default async function Page() {
// 此 fetch 将在 `next build` 期间在服务器上运行
const res = await fetch('https://api.example.com/...')
const data = await res.json()
return <main>...</main>
}Client Components#
如果你想在客户端执行数据获取,可以使用带有 SWR 的 Client Component 来记忆化请求。
'use client'
import useSWR from 'swr'
const fetcher = (url: string) => fetch(url).then((r) => r.json())
export default function Page() {
const { data, error } = useSWR(
`https://jsonplaceholder.typicode.com/posts/1`,
fetcher
)
if (error) return 'Failed to load'
if (!data) return 'Loading...'
return data.title
}'use client'
import useSWR from 'swr'
const fetcher = (url) => fetch(url).then((r) => r.json())
export default function Page() {
const { data, error } = useSWR(
`https://jsonplaceholder.typicode.com/posts/1`,
fetcher
)
if (error) return 'Failed to load'
if (!data) return 'Loading...'
return data.title
}由于路由切换发生在客户端,其行为类似于传统的 SPA。例如,以下索引路由允许你在客户端导航到不同的文章:
import Link from 'next/link'
export default function Page() {
return (
<>
<h1>Index Page</h1>
<hr />
<ul>
<li>
<Link href="/post/1">Post 1</Link>
</li>
<li>
<Link href="/post/2">Post 2</Link>
</li>
</ul>
</>
)
}import Link from 'next/link'
export default function Page() {
return (
<>
<h1>Index Page</h1>
<p>
<Link href="/other">Other Page</Link>
</p>
</>
)
}支持的功能#
构建静态站点所需的大多数 Next.js 核心功能都受支持,包括:
- 使用
getStaticPaths时的动态路由 - 使用
next/link进行预取 - 预加载 JavaScript
- 动态导入
- 任何样式选项(例如 CSS Modules、styled-jsx)
- 客户端数据获取
getStaticPropsgetStaticPaths
图片优化#
通过在 next.config.js 中定义自定义图片 loader,可以将其与静态导出一起使用,通过 next/image 实现图片优化。例如,你可以使用 Cloudinary 之类的服务来优化图片:
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
loader: 'custom',
loaderFile: './my-loader.ts',
},
}
module.exports = nextConfig这个自定义 loader 将定义如何从远程源获取图片。例如,以下 loader 将构造 Cloudinary 的 URL:
export default function cloudinaryLoader({
src,
width,
quality,
}: {
src: string
width: number
quality?: number
}) {
const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`]
return `https://res.cloudinary.com/demo/image/upload/${params.join(
','
)}${src}`
}export default function cloudinaryLoader({ src, width, quality }) {
const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`]
return `https://res.cloudinary.com/demo/image/upload/${params.join(
','
)}${src}`
}然后你可以在应用程序中使用 next/image,定义指向 Cloudinary 中图片的相对路径:
import Image from 'next/image'
export default function Page() {
return <Image alt="turtles" src="/turtles.jpg" width={300} height={300} />
}import Image from 'next/image'
export default function Page() {
return <Image alt="turtles" src="/turtles.jpg" width={300} height={300} />
}Route Handlers#
运行 next build 时,Route Handlers 将渲染静态响应。仅支持 GET HTTP 方法。这可用于从缓存或未缓存的数据生成静态 HTML、JSON、TXT 或其他文件。为确保 Route Handlers 被预渲染,当启用静态导出时,你必须通过添加 export const dynamic = 'force-static' 将处理程序显式标记为静态。例如:
export const dynamic = 'force-static'
export async function GET() {
return Response.json({ name: 'Lee' })
}export const dynamic = 'force-static'
export async function GET() {
return Response.json({ name: 'Lee' })
}上述文件 app/data.json/route.ts 将在 next build 期间渲染为静态文件,生成包含 { name: 'Lee' } 的 data.json。
如果你需要从传入的请求中读取动态值,则无法使用静态导出。
Browser API#
Client Components 会在 next build 期间预渲染为 HTML。由于 window、localStorage 和 navigator 等 Web API 在服务器上不可用,你需要仅在浏览器中运行时才安全地访问这些 API。例如:
'use client';
import { useEffect } from 'react';
export default function ClientComponent() {
useEffect(() => {
// 现在你可以访问 `window`
console.log(window.innerHeight);
}, [])
return ...;
}不支持的功能#
需要 Node.js 服务器的功能,或无法在构建过程中计算的动态逻辑,均不支持:
- 动态路由与
dynamicParams: true一起使用 - 不带
generateStaticParams()的动态路由 - 依赖 Request 的 Route Handlers
- Cookies
- Rewrites
- Redirects
- Headers
- Proxy
- 增量静态再生(Incremental Static Regeneration)
- 使用默认
loader的图片优化 - Draft Mode
- Server Actions
- 拦截路由
在 next dev 中尝试使用其中任何功能都将导致错误,类似于在根布局中将 dynamic 选项设置为 error。
export const dynamic = 'error'部署#
通过静态导出,Next.js 可以部署和托管在任何能够提供 HTML/CSS/JS 静态资源的 Web 服务器上。
运行 next build 时,Next.js 会将静态导出生成到 out 文件夹中。例如,假设你有以下路由:
//blog/[id]
运行 next build 后,Next.js 将生成以下文件:
/out/index.html/out/404.html/out/blog/post-1.html/out/blog/post-2.html
如果你使用像 Nginx 这样的静态主机,可以配置从传入请求到正确文件的重写规则:
server {
listen 80;
server_name acme.com;
root /var/www/out;
location / {
try_files $uri $uri.html $uri/ =404;
}
# 当 `trailingSlash: false` 时,这是必需的。
# 当 `trailingSlash: true` 时,可以省略此项。
location /blog/ {
rewrite ^/blog/(.*)$ /blog/$1.html break;
}
error_page 404 /404.html;
location = /404.html {
internal;
}
}要部署到 GitHub Pages,请使用我们的模板创建新项目,或作为配置现有项目的参考。
版本历史#
| 版本 | 变更 |
|---|---|
v14.0.0 | next export 已被移除,取而代之的是 "output": "export" |
v13.4.0 | App Router(稳定版)增强了静态导出支持,包括使用 React Server Components 和 Route Handlers。 |
v13.3.0 | next export 已弃用,并被 "output": "export" 取代 |