静态导出
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 将生成一个包含应用程序 HTML/CSS/JS 资产的 out
文件夹。
支持的功能
Next.js 的核心已经被设计为支持静态导出。
服务器组件
当您运行 next build
以生成静态导出时,在 app
目录中使用的服务器组件将在构建期间运行,类似于传统的静态站点生成。
生成的组件将在初始页面加载时呈现为静态 HTML,对于客户端在路由之间导航则呈现为静态负载。 在使用静态导出时,除非它们使用动态服务器函数,否则不需要对服务器组件进行任何更改。
export default async function Page() {
// 此次获取将在 `next build` 期间在服务器上运行
const res = await fetch('https://api.example.com/...')
const data = await res.json()
return <main>...</main>
}
客户端组件
如果您想在客户端执行数据获取,可以使用具有 SWR 的客户端组件来缓存请求。
'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
}
由于路由转换发生在客户端,这就像传统的 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>
</>
)
}
图像优化
通过 next/image
进行的图像优化可以与静态导出一起使用,
方法是在 next.config.js
中定义自定义图像加载器。
例如,您可以使用像 Cloudinary 这样的服务优化图像:
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
loader: 'custom',
loaderFile: './my-loader.ts',
},
}
module.exports = nextConfig
此自定义加载程序将定义如何从远程源获取图像。例如,以下加载程序将构造 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}`
}
然后,您可以在应用程序中使用 next/image
,定义 Cloudinary 图像的相对路径:
import Image from 'next/image'
export default function Page() {
return <Image alt="turtles" src="/turtles.jpg" width={300} height={300} />
}
路由处理程序
在运行 next build
时,路由处理程序将呈现静态响应。仅支持 GET HTTP 动词。
这可用于从缓存或未缓存的数据生成静态 HTML、JSON、TXT 或其他文件。例如:
// app/data.json/route.ts
export async function GET() {
return Response.json({ name: 'Lee' })
}
上述文件 app/data.json/route.ts
将在 next build
期间呈现为静态文件,
生成包含 { name: 'Lee' }
的 data.json
。
如果需要从传入请求中读取动态值,则无法使用静态导出。
浏览器 API
客户端组件在 next build
期间预渲染为 HTML。
由于 Web API,如 window、localStorage 和 navigator,在服务器上不可用,
因此只能在浏览器中运行时安全地访问这些 API。例如:
'use client';
import { useEffect } from 'react';
export default function ClientComponent() {
useEffect(() => {
// 您现在可以访问 `window`
console.log(window.innerHeight);
}, [])
return ...;
}
不支持的功能
不支持需要 Node.js 服务器的功能,或者在构建过程中无法计算的动态逻辑:
- 具有
dynamicParams: true
的动态路由 - 没有
generateStaticParams()
的动态路由 - 依赖 Request 的路由处理程序
- Cookies
- 重写
- 重定向
- 标头
- 中间件
- 增量静态再生
- 默认加载器的图像优化
- 草稿模式
尝试在 next dev
中使用这些功能将导致错误,类似于在根布局中将动态选项设置为错误。
部署
使用静态导出,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;
}
}
版本历史
版本 | 变更 |
---|---|
v14.0.0 | 移除了 next export ,改为使用 "output": "export" |
v13.4.0 | App Router (Stable) 添加了增强的静态导出支持,包括使用 React 服务器组件和路由处理程序。 |
v13.3.0 | next export 被弃用,替代为 "output": "export" |