Skip to main content

升级到版本 9

要升级到版本 9,请运行以下命令:

¥To upgrade to version 9, run the following command:

npm i next@9
yarn add next@9
pnpm up next@9
bun add next@9

很高兴知道:如果你使用的是 TypeScript,请确保还将 @types/react@types/react-dom 升级到相应的版本。

¥Good to know: If you are using TypeScript, ensure you also upgrade @types/react and @types/react-dom to their corresponding versions.

Vercel 上的生产部署

¥Production Deployment on Vercel

如果你之前在 vercel.json 文件中为动态路由配置了 routes,则在利用 Next.js 9 的新 动态路由功能 时可以删除这些规则。

¥If you previously configured routes in your vercel.json file for dynamic routes, these rules can be removed when leveraging Next.js 9's new Dynamic Routing feature.

Next.js 9 的动态路由会在 Vercel 上自动配置,不需要任何 vercel.json 自定义。

¥Next.js 9's dynamic routes are automatically configured on Vercel and do not require any vercel.json customization.

你可以阅读有关 动态路由在这里 的更多信息。

¥You can read more about Dynamic Routing here.

检查你的自定义应用文件 (pages/_app.js)

¥Check your Custom App File (pages/_app.js)

如果你之前复制了 定制 <App> 示例,则可以删除 getInitialProps

¥If you previously copied the Custom <App> example, you may be able to remove your getInitialProps.

pages/_app.js 中删除 getInitialProps(如果可能)对于利用新的 Next.js 功能非常重要!

¥Removing getInitialProps from pages/_app.js (when possible) is important to leverage new Next.js features!

以下 getInitialProps 不执行任何操作,可以删除:

¥The following getInitialProps does nothing and may be removed:

class MyApp extends App {
// Remove me, I do nothing!
static async getInitialProps({ Component, ctx }) {
let pageProps = {}

if (Component.getInitialProps) {
pageProps = await Component.getInitialProps(ctx)
}

return { pageProps }
}

render() {
// ... etc
}
}

重大变化

¥Breaking Changes

@zeit/next-typescript 不再需要

¥@zeit/next-typescript is no longer necessary

Next.js 现在将忽略用法 @zeit/next-typescript 并警告你将其删除。请从你的 next.config.js 中删除此插件。

¥Next.js will now ignore usage @zeit/next-typescript and warn you to remove it. Please remove this plugin from your next.config.js.

从自定义 .babelrc(如果存在)中删除对 @zeit/next-typescript/babel 的引用。

¥Remove references to @zeit/next-typescript/babel from your custom .babelrc (if present).

fork-ts-checker-webpack-plugin 的使用也应该从 next.config.js 中删除。

¥The usage of fork-ts-checker-webpack-plugin should also be removed from your next.config.js.

TypeScript 定义与 next 包一起发布,因此你需要卸载 @types/next,因为它们会发生冲突。

¥TypeScript Definitions are published with the next package, so you need to uninstall @types/next as they would conflict.

以下类型有所不同:

¥The following types are different:

此列表是由社区创建的,旨在帮助你升级,如果你发现其他差异,请向此列表发送拉取请求以帮助其他用户。

¥This list was created by the community to help you upgrade, if you find other differences please send a pull-request to this list to help other users.

从:

¥From:

import { NextContext } from 'next'
import { NextAppContext, DefaultAppIProps } from 'next/app'
import { NextDocumentContext, DefaultDocumentIProps } from 'next/document'

to

import { NextPageContext } from 'next'
import { AppContext, AppInitialProps } from 'next/app'
import { DocumentContext, DocumentInitialProps } from 'next/document'

config 键现在是页面上的导出

¥The config key is now an export on a page

你不能再从页面(即 export { config } / export const config ...)导出名为 config 的自定义变量。此导出的变量现在用于指定页面级 Next.js 配置,例如选择加入 AMP 和 API 路由功能。

¥You may no longer export a custom variable named config from a page (i.e. export { config } / export const config ...). This exported variable is now used to specify page-level Next.js configuration like Opt-in AMP and API Route features.

你必须将非 Next.js 专用的 config 导出重命名为不同的名称。

¥You must rename a non-Next.js-purposed config export to something different.

加载时 next/dynamic 不再默认渲染 "加载中..."

¥next/dynamic no longer renders "loading..." by default while loading

动态组件在加载时默认不会渲染任何内容。你仍然可以通过设置 loading 属性来自定义此行为:

¥Dynamic components will not render anything by default while loading. You can still customize this behavior by setting the loading property:

import dynamic from 'next/dynamic'

const DynamicComponentWithCustomLoading = dynamic(
() => import('../components/hello2'),
{
loading: () => <p>Loading</p>,
}
)

withAmp 已被删除,以支持导出的配置对象

¥withAmp has been removed in favor of an exported configuration object

Next.js 现在有了页面级配置的概念,因此为了保持一致性,withAmp 高阶组件已被删除。

¥Next.js now has the concept of page-level configuration, so the withAmp higher-order component has been removed for consistency.

通过在 Next.js 项目的根目录中运行以下命令,可以自动迁移此更改:

¥This change can be automatically migrated by running the following commands in the root of your Next.js project:

curl -L https://github.com/vercel/next-codemod/archive/master.tar.gz | tar -xz --strip=2 next-codemod-master/transforms/withamp-to-config.js npx jscodeshift -t ./withamp-to-config.js pages/**/*.js

要手动执行此迁移,或查看 codemod 将生成的内容,请参见下文:

¥To perform this migration by hand, or view what the codemod will produce, see below:

¥Before

import { withAmp } from 'next/amp'

function Home() {
return <h1>My AMP Page</h1>
}

export default withAmp(Home)
// or
export default withAmp(Home, { hybrid: true })

¥After

export default function Home() {
return <h1>My AMP Page</h1>
}

export const config = {
amp: true,
// or
amp: 'hybrid',
}

next export 不再将页面导出为 index.html

¥next export no longer exports pages as index.html

以前,导出 pages/about.js 将导致 out/about/index.html。此行为已更改为 out/about.html

¥Previously, exporting pages/about.js would result in out/about/index.html. This behavior has been changed to result in out/about.html.

你可以通过创建具有以下内容的 next.config.js 来恢复到以前的行为:

¥You can revert to the previous behavior by creating a next.config.js with the following content:

module.exports = {
trailingSlash: true,
}

pages/api/ 被区别对待

¥pages/api/ is treated differently

pages/api/ 中的页面现在被视为 API 路由。此目录中的页面将不再包含客户端包。

¥Pages in pages/api/ are now considered API Routes. Pages in this directory will no longer contain a client-side bundle.

已弃用的功能

¥Deprecated Features

next/dynamic 已弃用一次加载多个模块

¥next/dynamic has deprecated loading multiple modules at once

next/dynamic 中已弃用一次加载多个模块的功能,以更接近 React 的实现(React.lazySuspense)。

¥The ability to load multiple modules at once has been deprecated in next/dynamic to be closer to React's implementation (React.lazy and Suspense).

更新依赖于此行为的代码相对简单!我们提供了一个之前/之后的示例来帮助你迁移应用:

¥Updating code that relies on this behavior is relatively straightforward! We've provided an example of a before/after to help you migrate your application:

¥Before

import dynamic from 'next/dynamic'

const HelloBundle = dynamic({
modules: () => {
const components = {
Hello1: () => import('../components/hello1').then((m) => m.default),
Hello2: () => import('../components/hello2').then((m) => m.default),
}

return components
},
render: (props, { Hello1, Hello2 }) => (
<div>
<h1>{props.title}</h1>
<Hello1 />
<Hello2 />
</div>
),
})

function DynamicBundle() {
return <HelloBundle title="Dynamic Bundle" />
}

export default DynamicBundle

¥After

import dynamic from 'next/dynamic'

const Hello1 = dynamic(() => import('../components/hello1'))
const Hello2 = dynamic(() => import('../components/hello2'))

function HelloBundle({ title }) {
return (
<div>
<h1>{title}</h1>
<Hello1 />
<Hello2 />
</div>
)
}

function DynamicBundle() {
return <HelloBundle title="Dynamic Bundle" />
}

export default DynamicBundle