instant
为路由片段配置即时导航验证。
instant 路由片段配置控制 Next.js 如何验证进入该片段的导航是否会产生即时 UI。
Next.js 使用预取为当前页面上的所有应用内链接预加载导航。但是,客户端数据获取或来自服务器的部分预渲染结果可能导致导航无法立即更新 UI。为帮助您构建感觉快速的导航,instant 让您可以告诉 Next.js 对通过该片段的导航有何预期。例如,您可以指明进入该片段的导航应生成即时渲染的 UI,而无需等待任何外部加载的数据。您也可以指明导航不要求是即时的。
当某个片段被配置为预期即时 UI 时,Next.js 会显示应用中任何会阻止导航立即更新 UI 的代码。有关端到端的演示,请参阅即时导航指南。
小知识:
instant导出仅在启用cacheComponents时有效。instant不能在客户端组件中使用。否则会抛出错误。- Next.js 在开发环境中不执行预取,因此导航可能不像在生产环境中那样即时。验证反映的是
next start期间启用预取后的行为。
export const instant = true
export default function Page() {
return <div>...</div>
}export const instant = true
export default function Page() {
return <div>...</div>
}参考#
该导出接受:
true:使该片段选择加入全局配置的任意级别的验证(请参阅配置验证默认值)。使用框架默认值时,验证仅在开发环境中运行,并在开发浮层中显示错误。false:使该片段选择退出(请参阅禁用即时导航)。- 一个对象:选择加入并提供额外选项。请参阅
level。
level#
设置该片段运行验证的严重级别。
export const instant = {
level: 'warning',
}'warning':仅在开发环境中验证。错误显示在开发浮层中;构建不受影响。
未来将支持在构建期间进行验证的验证级别。除非您启用了实验性验证模式,否则无需指定 level,因为唯一可用的级别是 "warning"。
当省略 level(或使用 instant = true)时,该片段将按全局配置的任意级别进行验证——请参阅配置验证默认值。
禁用即时导航#
在布局或页面上设置 false,表示导航到该片段时允许阻塞。
当更深层级的页面应该是即时的,但其祖先做不到时,这很有用。例如,如果共享布局无法即时加载,但您仍想断言该布局下的页面可以即时导航,可以确保这些页面设置 instant = true,而共享布局设置 instant = false。
export const instant = falseexport const instant = true从外部进入标签页的导航允许在布局处阻塞。标签页之间的导航会验证是否为即时 UI。
在布局上设置 instant = false 不会禁用所有子页面的导航验证。该共享布局下页面之间的导航仍会验证,包括默认验证的页面。要让子页面退出验证,请从该页面导出 instant = false。
无需仅仅因为祖先做了某些阻塞操作,就给即时页面的祖先添加 false。更高层级的 instant = true 不会强制其后代进行验证,让祖先不配置也是可以的。只有在您已将更深层级的页面配置为即时,并且需要豁免经过阻塞祖先的导航时,才使用 false。
instant = false 控制的是即时导航验证。路由仍使用预渲染和流式传输。请参阅状态码。
客户端组件页面#
instant 导出不能在客户端组件模块中使用。如果您的页面带有 'use client' 指令,请将其现有组件移到单独的文件中,例如 app/dashboard/dashboard.tsx(或 dashboard.js),并将 'use client' 保留在该文件中。然后从一个导出 instant = false 的服务器组件页面渲染它:
import Dashboard from './dashboard'
export const instant = false
export default function Page() {
return <Dashboard />
}import Dashboard from './dashboard'
export const instant = false
export default function Page() {
return <Dashboard />
}该页面拥有验证配置,Dashboard 仍然是客户端组件。传递 Dashboard 使用的任何页面 props。
禁用静态外壳验证#
缓存组件(Cache Components)还会验证应用中的每个页面在预渲染时是否产生非空的静态外壳。要让某个路由退出此验证,请确保该路由树中最高的 instant 配置为 false——对于静态外壳检查,树中较高位置的 false 优先于更深层的任何 true。
在根布局上设置 false 会为整个应用禁用静态外壳验证。请将 false 放在尽可能低的位置——只提升到覆盖您想要退出的路由所需的高度——以便应用的其余部分继续接受验证。
验证如何工作#
instant 会在路由中的每个共享布局边界触发验证。验证在开发期间运行(在页面加载和 HMR 更新时),并在开发错误浮层中显示错误。
每个错误都会指出会阻塞导航的组件。修复方法通常是使用 use cache 缓存数据,或用 <Suspense> 边界包裹它。
instant 与 ensureStatic 的区别#
instant 验证导航是否立即显示 UI。ensureStatic 要求选定的服务器渲染输出是静态的,而不是为每个请求渲染。路由可以是完全静态的,但仍会阻塞导航,例如当客户端组件在浏览器中加载数据时。
配置验证默认值#
默认情况下(validationLevel: 'warning'),缓存组件(Cache Components)应用会在开发环境中验证每个 Page 和 Default 片段。experimental.instantInsights.validationLevel 配置可调整此行为——例如,将验证限制为通过 instant 显式选择加入的片段。
module.exports = {
experimental: {
instantInsights: {
validationLevel: 'warning',
},
},
}支持的级别有:
'warning'(框架默认值):每个 Page 和 Default 片段都隐式地以 warning 级别验证(仅限开发环境)。'manual-warning':仅验证具有显式instant的片段,以 warning 级别验证(仅限开发环境)。
在片段上设置 instant = false 会使其完全退出验证。
小知识:
- 框架默认值在未来版本中可能会更改,以让用户选择加入更高级别的验证。由于此功能是实验性的,这种更改不被视为破坏性更改。要固定特定行为,请显式设置
validationLevel。- 框架合成的错误路由(
/_global-error、/_not-found)不参与隐式验证。要验证它们,请使用instant显式选择加入。
检查加载状态#
当启用缓存组件(Cache Components)时,Navigation Inspector 可用:
module.exports = {
cacheComponents: true,
}打开 Next.js DevTools 并选择 Navigation Inspector,然后打开 Pause on navigations(导航时暂停)。当该开关开启时:
- 刷新页面,在动态数据流入之前冻结为该路由生成的初始静态 UI。
- 点击链接,冻结目标路由的预取 UI。
当 UI 被冻结后,点击 Resume(继续)让当前导航完成。开关保持开启状态,因此下一次刷新或链接点击也会暂停。完成后将其关闭。同时使用页面刷新和链接点击,检查首次访问和导航时的加载状态是否正确。
测试即时导航#
借助缓存组件(Cache Components),您还可以测试导航后立即可见的内容,即在动态内容流入之前的内容。@next/playwright 中的 instant() 辅助函数会暂停这些内容,同时您的测试会检查初始加载时的静态外壳或客户端导航时的预取 UI。
此辅助函数与 export const instant 路由选项相互独立。有关设置和示例,请参阅测试即时导航。
已知问题:项目间共享 cookie#
DevTools 使用 next-instant-navigation-testing cookie 来阻止动态内容并将页面冻结在即时 UI 状态。由于 cookie 的作用域是域名而非端口,在同一域名(通常是 localhost)上运行多个项目意味着该 cookie 会在它们之间共享,可能导致意外行为。在切换项目时,请清除该 cookie 或关闭 Navigation Inspector 面板,以避免问题。
小知识: 此问题将在该功能稳定化过程中修复。
TypeScript#
type InstantConfig =
| true
| false
| {
level?: 'warning'
}
export const instant: InstantConfig = true版本历史#
| 版本 | 变更 |
|---|---|
v16.3.0 | instant 导出稳定,取代 unstable_instant(仅限缓存组件)。 |