[Next] next中文文档

Next.js 是一个轻量级的 React 服务端渲染应用框架。

怎么使用

安装

在项目文件夹中运行:

npm install --save next react react-dom

将下面脚本添加到 package.json 中:

{

  "scripts": {

    "dev": "next",

    "build": "next build",

    "start": "next start"

  }

}

下面, 文件系统是主要的 API. 每个.js 文件将变成一个路由，自动处理和渲染。

新建 ./pages/index.js 到你的项目中:

export default () => <div>Welcome to next.js!</div>

运行 npm run dev 命令并打开 http://localhost:3000。要使用其他端口，你可以运行 npm run dev -- -p <your port here>.

到目前为止，我们做到:

自动打包编译 (使用 webpack 和 babel)
热加载
以 ./pages作为服务的渲染和索引
静态文件服务. ./public/ 映射到 / (可以创建一个静态目录在你的项目中)

这里有个简单的案例，可以下载看看 sample app - nextgram

代码自动分割

每个页面只会导入import中绑定以及被用到的代码. 这意味着页面不会加载不必要的代码

import cowsay from 'cowsay-browser'

export default () => <pre>{cowsay.say({ text: 'hi there!' })}</pre>

CSS

支持嵌入样式

案例

Basic css

我们绑定 styled-jsx 来生成独立作用域的 CSS. 目标是支持 "shadow CSS",但是不支持独立模块作用域的 JS.

export default () => (

  <div>

    Hello world

    <p>scoped!</p>

    <style jsx>{`

      p {

        color: blue;

      }

      div {

        background: red;

      }

      @media (max-width: 600px) {

        div {

          background: blue;

        }

      }

    `}</style>

    <style global jsx>{`

      body {

        background: black;

      }

    `}</style>

  </div>

)

想查看更多案例可以点击 styled-jsx documentation.

内嵌样式

Examples

有些情况可以使用 CSS 内嵌 JS 写法。如下所示：

export default () => <p style={{ color: 'red' }}>hi there</p>

更复杂的内嵌样式解决方案，特别是服务端渲染时的样式更改。我们可以通过包裹自定义 Document，来添加样式，案例如下：custom <Document>

使用 CSS / Sass / Less / Stylus files

支持用.css, .scss, .less or .styl，需要配置默认文件 next.config.js，具体可查看下面链接

静态文件服务（如图像）

在根目录下新建文件夹叫public。代码可以通过/来引入相关的静态资源。

export default () => <img src="/my-image.png" alt="my image" />

注意：不要自定义静态文件夹的名字，只能叫public ，因为只有这个名字 Next.js 才会把它当作静态资源。

生成`<head>`

<head>

Examples

我们设置一个内置组件来装载<head>到页面中。

import Head from 'next/head'

export default () => (

  <div>

    <Head>

      <title>My page title</title>

      <meta name="viewport" content="initial-scale=1.0, width=device-width" />

    </Head>

    <p>Hello world!</p>

  </div>

)

我们定义key属性来避免重复的<head>标签，保证<head>只渲染一次，如下所示：

import Head from 'next/head'

export default () => (

  <div>

    <Head>

      <title>My page title</title>

      <meta

        name="viewport"

        content="initial-scale=1.0, width=device-width"

        key="viewport"

      />

    </Head>

    <Head>

      <meta

        name="viewport"

        content="initial-scale=1.2, width=device-width"

        key="viewport"

      />

    </Head>

    <p>Hello world!</p>

  </div>

)

只有第二个<meta name="viewport" />才被渲染。

注意：在卸载组件时，<head>的内容将被清除。请确保每个页面都在其<head>定义了所需要的内容，而不是假设其他页面已经加过了

获取数据以及组件生命周期

Examples

Data fetch

当你需要状态，生命周期钩子或初始数据填充时，你可以导出React.Component（而不是上面的无状态函数），如下所示：

import React from 'react'

export default class extends React.Component {

  static async getInitialProps({ req }) {

    const userAgent = req ? req.headers['user-agent'] : navigator.userAgent

    return { userAgent }

  }

  render() {

    return <div>Hello World {this.props.userAgent}</div>

  }

}

请注意，当页面渲染时加载数据，我们使用了一个异步静态方法getInitialProps。它能异步获取 JS 普通对象，并绑定在props上。

当服务渲染时，getInitialProps将会把数据序列化，就像JSON.stringify。所以确保getInitialProps返回的是一个普通 JS 对象，而不是Date, Map 或 Set类型。

当页面初次加载时，getInitialProps只会在服务端执行一次。getInitialProps只有在路由切换的时候（如Link组件跳转或路由自定义跳转）时，客户端的才会被执行。

当页面初始化加载时，getInitialProps仅在服务端上执行。只有当路由跳转（Link组件跳转或 API 方法跳转）时，客户端才会执行getInitialProps。

注意：getInitialProps将不能在子组件中使用。只能在pages页面中使用。

只有服务端用到的模块放在getInitialProps里，请确保正确的导入了它们，可参考import them properly。

否则会拖慢你的应用速度。

你也可以给无状态组件定义getInitialProps：

const Page = ({ stars }) => <div>Next stars: {stars}</div>

Page.getInitialProps = async ({ req }) => {

  const res = await fetch('https://api.github.com/repos/zeit/next.js')

  const json = await res.json()

  return { stars: json.stargazers_count }

}

export default Page

getInitialProps入参对象的属性如下：

pathname - URL 的 path 部分
query - URL 的 query 部分，并被解析成对象
asPath - 显示在浏览器中的实际路径（包含查询部分），为String类型
req - HTTP 请求对象 (仅限服务器端)
res - HTTP 返回对象 (仅限服务器端)
jsonPageRes - 获取响应对象（仅限客户端）
err - 渲染过程中的任何错误

路由

Next.js 不会随应用程序中每个可能的路由一起发布路由清单，因此当前页面不知道客户端上的任何其他页面。出于可扩展性考虑，所有后续路由都会惰性加载。

`<Link>`用法

Examples

Hello World

可以用 <Link> 组件实现客户端的路由切换。

基本例子

参考下面的两个页面:

// pages/index.js

import Link from 'next/link'

function Home() {

  return (

    <div>

      Click{' '}

      <Link href="/about">

        <a>here</a>

      </Link>{' '}

      to read more

    </div>

  )

}

export default Home

// pages/about.js

function About() {

  return <p>Welcome to About!</p>

}

export default About

自定义路由 (使用 URL 中的 props)

<Link> 组件有两个主要属性:

href: pages目录内的路径+查询字符串.
as: 将在浏览器 URL 栏中呈现的路径.

例子:

假设你有个这样的路由 /post/:slug.
你可以创建文件 pages/post.js

class Post extends React.Component {

  static async getInitialProps({ query }) {

    console.log('SLUG', query.slug)

    return {}

  }

  render() {

    return <h1>My blog post</h1>

  }

}

export default Post

将路由添加到 express (或者其他服务端) 的 server.js 文件 (这仅适用于 SSR). 这将解析/post/:slug到pages/post.js并在 getInitialProps 中提供slug作为查询的一部分。

server.get('/post/:slug', (req, res) => {

  return app.render(req, res, '/post', { slug: req.params.slug })

})

对于客户端路由，使用 next/link:

<Link href="/post?slug=something" as="/post/something">

注意：可以使用<Link prefetch>使链接和预加载在后台同时进行，来达到页面的最佳性能。

客户端路由行为与浏览器很相似：

获取组件
如果组件定义了getInitialProps，则获取数据。如果有错误情况将会渲染 _error.js。
1 和 2 都完成了，pushState执行，新组件被渲染。

如果需要注入pathname, query 或 asPath到你组件中，你可以使用withRouter。

URL 对象

Examples

With URL Object Routing

组件<Link>接收 URL 对象，而且它会自动格式化生成 URL 字符串

// pages/index.js

import Link from 'next/link'

export default () => (

  <div>

    Click{' '}

    <Link href={{ pathname: '/about', query: { name: 'Zeit' } }}>

      <a>here</a>

    </Link>{' '}

    to read more

  </div>

)

将生成 URL 字符串/about?name=Zeit，你可以使用任何在Node.js URL module documentation定义过的属性。

替换路由

<Link>组件默认将新 url 推入路由栈中。你可以使用replace属性来防止添加新输入。

// pages/index.js

import Link from 'next/link'

export default () => (

  <div>

    Click{' '}

    <Link href="/about" replace>

      <a>here</a>

    </Link>{' '}

    to read more

  </div>

)

组件支持点击事件 `onClick`

<Link>支持每个组件所支持的onClick事件。如果你不提供<a>标签，只会处理onClick事件而href将不起作用。

// pages/index.js

import Link from 'next/link'

export default () => (

  <div>

    Click{' '}

    <Link href="/about">

      <img src="/static/image.png" alt="image" />

    </Link>

  </div>

)

暴露 `href` 给子元素

如子元素是一个没有 href 属性的<a>标签，我们将会指定它以免用户重复操作。然而有些时候，我们需要里面有<a>标签，但是Link组件不会被识别成超链接，结果不能将href传递给子元素。在这种场景下，你可以定义一个Link组件中的布尔属性passHref，强制将href传递给子元素。

注意: 使用a之外的标签而且没有通过passHref的链接可能会使导航看上去正确，但是当搜索引擎爬行检测时，将不会识别成链接（由于缺乏 href 属性），这会对你网站的 SEO 产生负面影响。

import Link from 'next/link'

import Unexpected_A from 'third-library'

export default ({ href, name }) => (

  <Link href={href} passHref>

    <Unexpected_A>{name}</Unexpected_A>

  </Link>

)

禁止滚动到页面顶部

<Link>的默认行为就是滚到页面顶部。当有 hash 定义时（＃），页面将会滚动到对应的 id 上，就像<a>标签一样。为了预防滚动到顶部，可以给<Link>加

scroll={false}属性：

<Link scroll={false} href="/?counter=10"><a>Disables scrolling</a></Link>

<Link href="/?counter=10"><a>Changes with scrolling to top</a></Link>

命令式

Examples

你也可以用next/router实现客户端路由切换

import Router from 'next/router'

export default () => (

  <div>

    Click <span onClick={() => Router.push('/about')}>here</span> to read more

  </div>

)

拦截器 `popstate`

有些情况（比如使用custom router），你可能想监听popstate，在路由跳转前做一些动作。

比如，你可以操作 request 或强制 SSR 刷新

import Router from 'next/router'

Router.beforePopState(({ url, as, options }) => {

  // I only want to allow these two routes!

  if (as !== '/' || as !== '/other') {

    // Have SSR render bad routes as a 404.

    window.location.href = as

    return false

  }

  return true

})

如果你在beforePopState中返回 false，Router将不会执行popstate事件。

例如Disabling File-System Routing。

以上Router对象的 API 如下：

route - 当前路由，为String类型
pathname - 不包含查询内容的当前路径，为String类型
query - 查询内容，被解析成Object类型. 默认为{}
asPath - 展现在浏览器上的实际路径，包含查询内容，为String类型
push(url, as=url) - 用给定的 url 调用pushState
replace(url, as=url) - 用给定的 url 调用replaceState
beforePopState(cb=function) - 在路由器处理事件之前拦截.

push 和 replace 函数的第二个参数as，是为了装饰 URL 作用。如果你在服务器端设置了自定义路由将会起作用。

URL 对象用法

push 或 replace可接收的 URL 对象（<Link>组件的 URL 对象一样）来生成 URL。

import Router from 'next/router'

const handler = () =>

  Router.push({

    pathname: '/about',

    query: { name: 'Zeit' },

  })

export default () => (

  <div>

    Click <span onClick={handler}>here</span> to read more

  </div>

)

也可以像<Link>组件一样添加额外的参数。

路由事件

你可以监听路由相关事件。

下面是支持的事件列表：

routeChangeStart(url) - 路由开始切换时触发
routeChangeComplete(url) - 完成路由切换时触发
routeChangeError(err, url) - 路由切换报错时触发
beforeHistoryChange(url) - 浏览器 history 模式开始切换时触发
hashChangeStart(url) - 开始切换 hash 值但是没有切换页面路由时触发
hashChangeComplete(url) - 完成切换 hash 值但是没有切换页面路由时触发

这里的url是指显示在浏览器中的 url。如果你用了Router.push(url, as)（或类似的方法），那浏览器中的 url 将会显示 as 的值。

下面是如何正确使用路由事件routeChangeStart的例子：

const handleRouteChange = url => {

  console.log('App is changing to: ', url)

}

Router.events.on('routeChangeStart', handleRouteChange)

如果你不想再监听该事件，你可以用off事件去取消监听：

Router.events.off('routeChangeStart', handleRouteChange)

如果路由加载被取消（比如快速连续双击链接），routeChangeError将触发。传递 err,并且属性 cancelled 的值为 true。

Router.events.on('routeChangeError', (err, url) => {

  if (err.cancelled) {

    console.log(`Route to ${url} was cancelled!`)

  }

})

浅层路由

Examples

Shallow Routing

浅层路由允许你改变 URL 但是不执行getInitialProps生命周期。你可以加载相同页面的 URL，得到更新后的路由属性pathname和query，并不失去 state 状态。

你可以给Router.push 或 Router.replace方法加shallow: true参数。如下面的例子所示：

// Current URL is "/"

const href = '/?counter=10'

const as = href

Router.push(href, as, { shallow: true })

现在 URL 更新为/?counter=10。在组件里查看this.props.router.query你将会看到更新的 URL。

你可以在componentdidupdate钩子函数中监听 URL 的变化。

componentDidUpdate(prevProps) {

  const { pathname, query } = this.props.router

  // verify props have changed to avoid an infinite loop

  if (query.id !== prevProps.router.query.id) {

    // fetch data based on the new query

  }

}

注意:

浅层路由只作用于相同 URL 的参数改变，比如我们假定有个其他路由about，而你向下面代码样运行:
Router.push('/?counter=10', '/about?counter=10', { shallow: true })
那么这将会出现新页面，即使我们加了浅层路由，但是它还是会卸载当前页，会加载新的页面并触发新页面的getInitialProps。

高阶组件

Examples

Using the `withRouter` utility

如果你想应用里每个组件都处理路由对象，你可以使用withRouter高阶组件。下面是如何使用它：

import { withRouter } from 'next/router'

const ActiveLink = ({ children, router, href }) => {

  const style = {

    marginRight: 10,

    color: router.pathname === href ? 'red' : 'black',

  }

  const handleClick = e => {

    e.preventDefault()

    router.push(href)

  }

  return (

    <a href={href} onClick={handleClick} style={style}>

      {children}

    </a>

  )

}

export default withRouter(ActiveLink)

上面路由对象的 API 可以参考next/router.

预加载页面

⚠️ 只有生产环境才有此功能 ⚠️

Examples

Prefetching

Next.js 有允许你预加载页面的 API。

用 Next.js 服务端渲染你的页面，可以达到所有你应用里所有未来会跳转的路径即时响应，有效的应用 Next.js，可以通过预加载应用程序的功能，最大程度的初始化网站性能。查看更多.

Next.js 的预加载功能只预加载 JS 代码。当页面渲染时，你可能需要等待数据请求。

`<Link>`用法

你可以给添加 prefetch 属性，Next.js 将会在后台预加载这些页面。

import Link from 'next/link'

// example header component

export default () => (

  <nav>

    <ul>

      <li>

        <Link prefetch href="/">

          <a>Home</a>

        </Link>

      </li>

      <li>

        <Link prefetch href="/about">

          <a>About</a>

        </Link>

      </li>

      <li>

        <Link prefetch href="/contact">

          <a>Contact</a>

        </Link>

      </li>

    </ul>

  </nav>

)

命令式 prefetch 写法

大多数预加载是通过处理的，但是我们还提供了命令式 API 用于更复杂的场景。

import { withRouter } from 'next/router'

export default withRouter(({ router }) => (

  <div>

    <a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>

      A route transition will happen after 100ms

    </a>

    {// but we can prefetch it!

    router.prefetch('/dynamic')}

  </div>

))

路由实例只允许在应用程序的客户端。以防服务端渲染发生错误，建议 prefetch 事件写在componentDidMount()生命周期里。

import React from 'react'

import { withRouter } from 'next/router'

class MyLink extends React.Component {

  componentDidMount() {

    const { router } = this.props

    router.prefetch('/dynamic')

  }

  render() {

    const { router } = this.props

    return (

      <div>

        <a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>

          A route transition will happen after 100ms

        </a>

      </div>

    )

  }

}

export default withRouter(MyLink)

自定义服务端路由

Examples

一般你使用next start命令来启动 next 服务，你还可以编写代码来自定义路由，如使用路由正则等。

当使用自定义服务文件，如下面例子所示叫 server.js 时，确保你更新了 package.json 中的脚本。

{

  "scripts": {

    "dev": "node server.js",

    "build": "next build",

    "start": "NODE_ENV=production node server.js"

  }

}

下面这个例子使 /a 路由解析为./pages/b，以及/b 路由解析为./pages/a;

// This file doesn't go through babel or webpack transformation.

// Make sure the syntax and sources this file requires are compatible with the current node version you are running

// See https://github.com/zeit/next.js/issues/1245 for discussions on Universal Webpack or universal Babel

const { createServer } = require('http')

const { parse } = require('url')

const next = require('next')

const dev = process.env.NODE_ENV !== 'production'

const app = next({ dev })

const handle = app.getRequestHandler()

app.prepare().then(() => {

  createServer((req, res) => {

    // Be sure to pass `true` as the second argument to `url.parse`.

    // This tells it to parse the query portion of the URL.

    const parsedUrl = parse(req.url, true)

    const { pathname, query } = parsedUrl

    if (pathname === '/a') {

      app.render(req, res, '/b', query)

    } else if (pathname === '/b') {

      app.render(req, res, '/a', query)

    } else {

      handle(req, res, parsedUrl)

    }

  }).listen(3000, err => {

    if (err) throw err

    console.log('> Ready on http://localhost:3000')

  })

})

next的 API 如下所示

next(opts: object)

opts 的属性如下:

dev (boolean) 判断 Next.js 应用是否在开发环境 - 默认false
dir (string) Next 项目路径 - 默认'.'
quiet (boolean) 是否隐藏包含服务端消息在内的错误信息 - 默认false
conf (object) 与next.config.js的对象相同 - 默认{}

生产环境的话，可以更改 package.json 里的start脚本为NODE_ENV=production node server.js。

禁止文件路由

默认情况，Next将会把/pages下的所有文件匹配路由（如/pages/some-file.js 渲染为 site.com/some-file）

如果你的项目使用自定义路由，那么有可能不同的路由会得到相同的内容，可以优化 SEO 和用户体验。

禁止路由链接到/pages下的文件，只需设置next.config.js文件如下所示：

// next.config.js

module.exports = {

  useFileSystemPublicRoutes: false,

}

注意useFileSystemPublicRoutes只禁止服务端的文件路由；但是客户端的还是禁止不了。

你如果想配置客户端路由不能跳转文件路由，可以参考Intercepting popstate。

动态前缀

有时你需要设置动态前缀，可以在请求时设置assetPrefix改变前缀。

使用方法如下：

const next = require('next')

const micro = require('micro')

const dev = process.env.NODE_ENV !== 'production'

const app = next({ dev })

const handleNextRequests = app.getRequestHandler()

app.prepare().then(() => {

  const server = micro((req, res) => {

    // Add assetPrefix support based on the hostname

    if (req.headers.host === 'my-app.com') {

      app.setAssetPrefix('http://cdn.com/myapp')

    } else {

      app.setAssetPrefix('')

    }

    handleNextRequests(req, res)

  })

  server.listen(port, err => {

    if (err) {

      throw err

    }

    console.log(`> Ready on http://localhost:${port}`)

  })

})

动态导入

Examples

With Dynamic Import

ext.js 支持 JavaScript 的 TC39 提议dynamic import proposal。你可以动态导入 JavaScript 模块（如 React 组件）。

动态导入相当于把代码分成各个块管理。Next.js 服务端动态导入功能，你可以做很多炫酷事情。

下面介绍一些动态导入方式：

1. 基础用法 (也就是 SSR)

import dynamic from 'next/dynamic'

const DynamicComponent = dynamic(import('../components/hello'))

export default () => (

  <div>

    <Header />

    <DynamicComponent />

    <p>HOME PAGE is here!</p>

  </div>

)

2. 自定义加载组件

import dynamic from 'next/dynamic'

const DynamicComponentWithCustomLoading = dynamic(

  import('../components/hello2'),

  {

    loading: () => <p>...</p>,

  }

)

export default () => (

  <div>

    <Header />

    <DynamicComponentWithCustomLoading />

    <p>HOME PAGE is here!</p>

  </div>

)

3. 禁止使用 SSR

import dynamic from 'next/dynamic'

const DynamicComponentWithNoSSR = dynamic(import('../components/hello3'), {

  ssr: false,

})

export default () => (

  <div>

    <Header />

    <DynamicComponentWithNoSSR />

    <p>HOME PAGE is here!</p>

  </div>

)

4. 同时加载多个模块

import dynamic from 'next/dynamic'

const HelloBundle = dynamic({

  modules: () => {

    const components = {

      Hello1: import('../components/hello1'),

      Hello2: import('../components/hello2'),

    }

    return components

  },

  render: (props, { Hello1, Hello2 }) => (

    <div>

      <h1>{props.title}</h1>

      <Hello1 />

      <Hello2 />

    </div>

  ),

})

export default () => <HelloBundle title="Dynamic Bundle" />

自定义 `<App>`

Examples

Using `_app.js` for layout

Using `_app.js` to override `componentDidCatch`

组件来初始化页面。你可以重写它来控制页面初始化，如下面的事：

当页面变化时保持页面布局
当路由变化时保持页面状态
使用componentDidCatch自定义处理错误
注入额外数据到页面里 (如 GraphQL 查询)

重写的话，新建./pages/_app.js文件，重写 App 模块如下所示：

import App, { Container } from 'next/app'

import React from 'react'

export default class MyApp extends App {

  static async getInitialProps({ Component, router, ctx }) {

    let pageProps = {}

    if (Component.getInitialProps) {

      pageProps = await Component.getInitialProps(ctx)

    }

    return { pageProps }

  }

  render() {

    const { Component, pageProps } = this.props

    return (

      <Container>

        <Component {...pageProps} />

      </Container>

    )

  }

}

自定义 `<Document>`

Examples

Styled components custom document

Google AMP

在服务端呈现
初始化服务端时添加文档标记元素
通常实现服务端渲染会使用一些 css-in-js 库，如styled-components, glamorous 或 emotion。styled-jsx是 Next.js 自带默认使用的 css-in-js 库

Next.js会自动定义文档标记，比如，你从来不需要添加<html>, <body>等。如果想自定义文档标记，你可以新建./pages/_document.js，然后扩展Document类：

// _document is only rendered on the server side and not on the client side

// Event handlers like onClick can't be added to this file

// ./pages/_document.js

import Document, { Head, Main, NextScript } from 'next/document'

export default class MyDocument extends Document {

  static async getInitialProps(ctx) {

    const initialProps = await Document.getInitialProps(ctx)

    return { ...initialProps }

  }

  render() {

    return (

      <html>

        <Head>

          <style>{`body { margin: 0 } /* custom! */`}</style>

        </Head>

        <body className="custom_class">

          <Main />

          <NextScript />

        </body>

      </html>

    )

  }

}

钩子getInitialProps接收到的参数ctx对象都是一样的

回调函数renderPage是会执行 React 渲染逻辑的函数(同步)，这种做法有助于此函数支持一些类似于 Aphrodite 的 renderStatic 等一些服务器端渲染容器。

注意：<Main />外的 React 组件将不会渲染到浏览器中，所以那添加应用逻辑代码。如果你页面需要公共组件（菜单或工具栏），可以参照上面说的App组件代替。

自定义 `renderPage`