screen shot 2016-10-25 at 2 37 27 pm [![NPM version](https://img.shields.io/npm/v/next.svg)](https://www.npmjs.com/package/next) [![Build Status](https://travis-ci.org/zeit/next.js.svg?branch=master)](https://travis-ci.org/zeit/next.js) [![Build status](https://ci.appveyor.com/api/projects/status/gqp5hs71l3ebtx1r/branch/master?svg=true)](https://ci.appveyor.com/project/arunoda/next-js/branch/master) [![Coverage Status](https://coveralls.io/repos/zeit/next.js/badge.svg?branch=master)](https://coveralls.io/r/zeit/next.js?branch=master) [![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/next-js) Next.js 是一个轻量级的 React 服务端渲染应用框架。 **可访问 [nextjs.org/learn](https://nextjs.org/learn) 开始学习 Next.js.** [README in English](README.md) --- - [怎么使用](#how-to-use) - [安装](#setup) - [代码自动分割](#automatic-code-splitting) - [CSS](#css) - [支持嵌入样式](#built-in-css-support) - [内嵌样式](#css-in-js) - [使用 CSS / Sass / Less / Stylus files](#importing-css--sass--less--stylus-files) - [静态文件服务(如图像)](#static-file-serving-eg-images) - [``](#populating-head) - [获取数据以及组件生命周期](#fetching-data-and-component-lifecycle) - [路由](#routing) - [`` 用法](#with-link) - [URL 对象](#with-url-object) - [替换路由](#replace-instead-of-push-url) - [组件支持点击事件`onClick`](#using-a-component-that-supports-onclick) - [暴露`href`给子元素](#forcing-the-link-to-expose-href-to-its-child) - [禁止滚动到页面顶部](#disabling-the-scroll-changes-to-top-on-page) - [命令式](#imperatively) - [拦截器 `popstate`](#intercepting-popstate) - [URL 对象用法](#with-url-object-1) - [路由事件](#router-events) - [浅层路由](#shallow-routing) - [高阶组件](#using-a-higher-order-component) - [预加载页面](#prefetching-pages) - [``用法](#with-link-1) - [命令式 prefetch 写法](#imperatively-1) - [自定义服务端路由](#custom-server-and-routing) - [禁止文件路由](#disabling-file-system-routing) - [动态前缀](#dynamic-assetprefix) - [动态导入](#dynamic-import) - [1. 基础支持 (同样支持 SSR)](#1-basic-usage-also-does-ssr) - [2. 自定义加载组件](#2-with-custom-loading-component) - [3. 禁止使用 SSR](#3-with-no-ssr) - [4. 同时加载多个模块](#4-with-multiple-modules-at-once) - [自定义 ``](#custom-app) - [自定义 ``](#custom-document) - [自定义错误处理](#custom-error-handling) - [渲染内置错误页面](#reusing-the-built-in-error-page) - [自定义配置](#custom-configuration) - [设置自定义构建目录](#setting-a-custom-build-directory) - [禁止 etag 生成](#disabling-etag-generation) - [配置 onDemandEntries](#configuring-the-ondemandentries) - [配置页面后缀名解析扩展](#configuring-extensions-looked-for-when-resolving-pages-in-pages) - [配置构建 ID](#configuring-the-build-id) - [自定义 webpack 配置](#customizing-webpack-config) - [自定义 babel 配置](#customizing-babel-config) - [暴露配置到服务端和客户端](#exposing-configuration-to-the-server--client-side) - [启动服务选择 hostname](#starting-the-server-on-alternative-hostname) - [CDN 支持前缀](#cdn-support-with-asset-prefix) - [项目部署](#production-deployment) - [浏览器支持](#browser-support) - [导出静态页面](#static-html-export) - [使用](#usage) - [限制](#limitation) - [多 zone](#multi-zones) - [怎么定义一个 zone](#how-to-define-a-zone) - [怎么合并他们](#how-to-merge-them) - [技巧](#recipes) - [FAQ](#faq) - [贡献](#contributing) - [作者](#authors) ## 怎么使用 ### 安装 安装它: ```bash npm install --save next react react-dom ``` 将下面脚本添加到 package.json 中: ```json { "scripts": { "dev": "next", "build": "next build", "start": "next start" } } ``` 下面, 文件系统是主要的 API. 每个`.js` 文件将变成一个路由,自动处理和渲染。 新建 `./pages/index.js` 到你的项目中: ```jsx export default () =>
Welcome to next.js!
``` 运行 `npm run dev` 命令并打开 `http://localhost:3000`。 如果你想使用其他端口,可运行 `npm run dev -- -p <设置端口号>`. 目前为止我们可以了解到: - 自动打包编译 (使用 webpack 和 babel) - 热加载 - 以 `./pages`作为服务端的渲染和索引 - Static file serving. `./static/` is mapped to `/static/` (given you [create a `./static/` directory](#static-file-serving-eg-images) inside your project) - 静态文件服务. `./static/` 映射到 `/static/` (可以 [创建一个静态目录](#static-file-serving-eg-images) 在你的项目中) 这里有个简单的案例,可以下载看看 [sample app - nextgram](https://github.com/zeit/nextgram) ### 代码自动分割 每个页面只会导入`import`中绑定以及被用到的代码. 也就是说并不会加载不需要的代码! ```jsx import cowsay from 'cowsay-browser' export default () =>
    {cowsay.say({ text: 'hi there!' })}
  
``` ### CSS #### 支持嵌入样式

案例

我们绑定 [styled-jsx](https://github.com/zeit/styled-jsx) 来生成独立作用域的 CSS. 目标是支持 "shadow CSS",但是 [不支持独立模块作用域的 JS](https://github.com/w3c/webcomponents/issues/71). ```jsx export default () =>
Hello world

scoped!

``` 想查看更多案例可以点击 [styled-jsx documentation](https://www.npmjs.com/package/styled-jsx)查看. #### 内嵌样式

Examples

有些情况可以使用 CSS 内嵌 JS 写法。如下所示: ```jsx export default () =>

hi there

``` 更复杂的内嵌样式解决方案,特别是服务端渲染的时样式更改。我们可以通过包裹自定义 Document,来添加样式,案例如下:[custom ``](#user-content-custom-document) #### 使用 CSS / Sass / Less / Stylus files 支持用`.css`, `.scss`, `.less` or `.styl`,需要配置默认文件 next.config.js,具体可查看下面链接 - [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css) - [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass) - [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less) - [@zeit/next-stylus](https://github.com/zeit/next-plugins/tree/master/packages/next-stylus) ### 静态文件服务(如图像) 在根目录下新建文件夹叫`static`。代码可以通过`/static/`来引入相关的静态资源。 ```jsx export default () => my image ``` _注意:不要自定义静态文件夹的名字,只能叫`static` ,因为只有这个名字 Next.js 才会把它当作静态资源。 ### 生成`` ``

Examples

我们设置一个内置组件来装载``到页面中。 ```jsx import Head from 'next/head' export default () =>
My page title

Hello world!

``` 我们定义`key`属性来避免重复的``标签,保证``只渲染一次,如下所示: ```jsx import Head from 'next/head' export default () => (
My page title

Hello world!

) ``` 只有第二个``才被渲染。 注意:在卸载组件时,``的内容将被清除。请确保每个页面都在其``定义了所需要的内容,而不是假设其他页面已经加过了 ### 获取数据以及组件生命周期

Examples

如果你需要一个有状态、生命周期或有初始数据的 React 组件(而不是上面的无状态函数),如下所示: ```jsx 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 (
Hello World {this.props.userAgent}
) } } ``` 相信你注意到,当页面渲染时加载数据,我们使用了一个异步方法`getInitialProps`。它能异步获取 JS 普通对象,并绑定在`props`上 当服务渲染时,`getInitialProps`将会把数据序列化,就像`JSON.stringify`。所以确保`getInitialProps`返回的是一个普通 JS 对象,而不是`Date`, `Map` 或 `Set`类型。 当页面初次加载时,`getInitialProps`只会在服务端执行一次。`getInitialProps`只有在路由切换的时候(如`Link`组件跳转或路由自定义跳转)时,客户端的才会被执行。 当页面初始化加载时,`getInitialProps`只会加载在服务端。只有当路由跳转(`Link`组件跳转或 API 方法跳转)时,客户端才会执行`getInitialProps`。 注意:`getInitialProps`将不能使用在子组件中。只能使用在`pages`页面中。
> 只有服务端用到的模块放在`getInitialProps`里,请确保正确的导入了它们,可参考[import them properly](https://arunoda.me/blog/ssr-and-server-only-modules)。 > 否则会拖慢你的应用速度。
你也可以给无状态组件定义`getInitialProps`: ```jsx const Page = ({ stars }) =>
Next stars: {stars}
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` - [获取数据响应对象](https://developer.mozilla.org/en-US/docs/Web/API/Response) (只有客户端有) - `err` - 渲染过程中的任何错误 ### 路由 #### ``用法

Examples

可以用 `` 组件实现客户端的路由切换。 ```jsx // pages/index.js import Link from 'next/link' export default () =>
Click{' '} here {' '} to read more
``` ```jsx // pages/about.js export default () =>

Welcome to About!

``` 注意:可以使用[``](#prefetching-pages)使链接和预加载在后台同时进行,来达到页面的最佳性能。 客户端路由行为与浏览器很相似: 1. 组件获取 2. 如果组件定义了`getInitialProps`,数据获取了。如果有错误情况将会渲染 `_error.js`。 3. 1和2都完成了,`pushState`执行,新组件被渲染。 如果需要注入`pathname`, `query` 或 `asPath`到你组件中,你可以使用[withRouter](#using-a-higher-order-component)。 ##### URL 对象

Examples

组件``接收 URL 对象,而且它会自动格式化生成 URL 字符串 ```jsx // pages/index.js import Link from 'next/link' export default () =>
Click{' '} here {' '} to read more
``` 将生成 URL 字符串`/about?name=Zeit`,你可以使用任何在[Node.js URL module documentation](https://nodejs.org/api/url.html#url_url_strings_and_url_objects)定义过的属性。 ##### 替换路由 ``组件默认将新 url 推入路由栈中。你可以使用`replace`属性来防止添加新输入。 ```jsx // pages/index.js import Link from 'next/link' export default () =>
Click{' '} here {' '} to read more
``` ##### 组件支持点击事件 `onClick` ``支持每个组件所支持的`onClick`事件。如果你不提供``标签,只会处理`onClick`事件而`href`将不起作用。 ```jsx // pages/index.js import Link from 'next/link' export default () =>
Click{' '} image
```
##### 暴露 `href` 给子元素 如子元素是一个没有 href 属性的``标签,我们将会指定它以免用户重复操作。然而有些时候,我们需要里面有``标签,但是`Link`组件不会被识别成*超链接*,结果不能将`href`传递给子元素。在这种场景下,你可以定义一个`Link`组件中的布尔属性`passHref`,强制将`href`传递给子元素。 **注意**: 使用`a`之外的标签而且没有通过`passHref`的链接可能会使导航看上去正确,但是当搜索引擎爬行检测时,将不会识别成链接(由于缺乏 href 属性),这会对你网站的 SEO 产生负面影响。 ```jsx import Link from 'next/link' import Unexpected_A from 'third-library' export default ({ href, name }) => {name} ``` ##### 禁止滚动到页面顶部 ``的默认行为就是滚到页面顶部。当有 hash 定义时(#),页面将会滚动到对应的 id 上,就像``标签一样。为了预防滚动到顶部,可以给``加 `scroll={false}`属性: ```jsx Disables scrolling Changes with scrolling to top ``` #### 命令式

Examples

你也可以用`next/router`实现客户端路由切换 ```jsx import Router from 'next/router' export default () =>
Click Router.push('/about')}>here to read more
``` #### 拦截器 `popstate` 有些情况(比如使用[custom router](#custom-server-and-routing)),你可能想监听[`popstate`](https://developer.mozilla.org/en-US/docs/Web/Events/popstate),在路由跳转前做一些动作。 比如,你可以操作 request 或强制 SSR 刷新 ```jsx 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](#disabling-file-system-routing)。 以上`Router`对象的 API 如下: - `route` - 当前路由的`String`类型 - `pathname` - 不包含查询内容的当前路径,为`String`类型 - `query` - 查询内容,被解析成`Object`类型. 默认为`{}` - `asPath` - 展现在浏览器上的实际路径,包含查询内容,为`String`类型 - `push(url, as=url)` - 页面渲染第一个参数 url 的页面,浏览器栏显示的是第二个参数 url - `replace(url, as=url)` - performs a `replaceState` call with the given url - `beforePopState(cb=function)` - 在路由器处理事件之前拦截. `push` 和 `replace` 函数的第二个参数`as`,是为了装饰 URL 作用。如果你在服务器端设置了自定义路由将会起作用。 ##### URL 对象用法 `push` 或 `replace`可接收的 URL 对象(``组件的 URL 对象一样)来生成 URL。 ```jsx import Router from 'next/router' const handler = () => Router.push({ pathname: '/about', query: { name: 'Zeit' } }) export default () =>
Click here to read more
``` 也可以像``组件一样添加额外的参数。 ##### 路由事件 你可以监听路由相关事件。 下面是事件支持列表: - `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`的例子: ```js const handleRouteChange = url => { console.log('App is changing to: ', url) } Router.events.on('routeChangeStart', handleRouteChange) ``` 如果你不想长期监听该事件,你可以用`off`事件去取消监听: ```js Router.events.off('routeChangeStart', handleRouteChange) ``` 如果路由加载被取消(比如快速连续双击链接) ```js Router.events.on('routeChangeError', (err, url) => { if (err.cancelled) { console.log(`Route to ${url} was cancelled!`) } }) ``` ##### 浅层路由

Examples

浅层路由允许你改变 URL 但是不执行`getInitialProps`生命周期。你可以加载相同页面的 URL,得到更新后的路由属性`pathname`和`query`,并不失去 state 状态。 你可以给`Router.push` 或 `Router.replace`方法加`shallow: true`参数。如下面的例子所示: ```js // 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`](https://facebook.github.io/react/docs/react-component.html#componentdidupdate)钩子函数中监听 URL 的变化。 ```js 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`,而你向下面代码样运行: > ```js > Router.push('/?counter=10', '/about?counter=10', { shallow: true }) > ``` > 那么这将会出现新页面,即使我们加了浅层路由,但是它还是会卸载当前页,会加载新的页面并触发新页面的`getInitialProps`。 #### 高阶组件

Examples

如果你想应用里每个组件都处理路由对象,你可以使用`withRouter`高阶组件。下面是如何使用它: ```jsx 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 ( {children} ) } export default withRouter(ActiveLink) ``` 上面路由对象的 API 可以参考[`next/router`](#imperatively). ### 预加载页面 ⚠️ 只有生产环境才有此功能 ⚠️

Examples

Next.js 有允许你预加载页面的 API。 用 Next.js 服务端渲染你的页面,可以达到所有你应用里所有未来会跳转的路径即时响应,有效的应用 Next.js,可以通过预加载应用程序的功能,最大程度的初始化网站性能。[查看更多](https://zeit.co/blog/next#anticipation-is-the-key-to-performance). > Next.js 的预加载功能只预加载 JS 代码。当页面渲染时,你可能需要等待数据请求。 #### ``用法 你可以给添加 `prefetch` 属性,Next.js 将会在后台预加载这些页面。 ```jsx import Link from 'next/link' // example header component export default () => ``` #### 命令式 prefetch 写法 大多数预加载是通过处理的,但是我们还提供了命令式 API 用于更复杂的场景。 ```jsx import { withRouter } from 'next/router' export default withRouter(({ router }) =>
setTimeout(() => router.push('/dynamic'), 100)}> A route transition will happen after 100ms {// but we can prefetch it! router.prefetch('/dynamic')}
) ``` 路由实例只允许在应用程序的客户端。以防服务端渲染发生错误,建议 prefetch 事件写在`componentDidMount()`生命周期里。 ```jsx 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 (
setTimeout(() => router.push('/dynamic'), 100)}> A route transition will happen after 100ms
) } } export default withRouter(MyLink) ``` ### 自定义服务端路由

Examples

一般你使用`next start`命令来启动 next 服务,你还可以编写代码来自定义路由,如使用路由正则等。 当使用自定义服务文件,如下面例子所示叫 server.js 时,确保你更新了 package.json 中的脚本。 ```json { "scripts": { "dev": "node server.js", "build": "next build", "start": "NODE_ENV=production node server.js" } } ``` 下面这个例子使 `/a` 路由解析为`./pages/b`,以及`/b` 路由解析为`./pages/a`; ```js // 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`文件如下所示: ```js // next.config.js module.exports = { useFileSystemPublicRoutes: false } ``` 注意`useFileSystemPublicRoutes`只禁止服务端的文件路由;但是客户端的还是禁止不了。 你如果想配置客户端路由不能跳转文件路由,可以参考[Intercepting `popstate`](#intercepting-popstate)。 #### 动态前缀 有时你需要设置动态前缀,可以在请求时设置`assetPrefix`改变前缀。 使用方法如下: ```js 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

ext.js 支持 JavaScript 的 TC39 提议[dynamic import proposal](https://github.com/tc39/proposal-dynamic-import)。你可以动态导入 JavaScript 模块(如 React 组件)。 动态导入相当于把代码分成各个块管理。Next.js 服务端动态导入功能,你可以做很多炫酷事情。 下面介绍一些动态导入方式: #### 1. 基础支持 (同样支持 SSR) ```jsx import dynamic from 'next/dynamic' const DynamicComponent = dynamic(import('../components/hello')) export default () =>

HOME PAGE is here!

``` #### 2. 自定义加载组件 ```jsx import dynamic from 'next/dynamic' const DynamicComponentWithCustomLoading = dynamic( import('../components/hello2'), { loading: () =>

...

} ) export default () =>

HOME PAGE is here!

``` #### 3. 禁止使用 SSR ```jsx import dynamic from 'next/dynamic' const DynamicComponentWithNoSSR = dynamic(import('../components/hello3'), { ssr: false }) export default () =>

HOME PAGE is here!

``` #### 4. 同时加载多个模块 ```jsx 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 }) =>

{props.title}

}) export default () => ``` ### 自定义 ``

Examples

组件来初始化页面。你可以重写它来控制页面初始化,如下面的事: - 当页面变化时保持页面布局 - 当路由变化时保持页面状态 - 使用`componentDidCatch`自定义处理错误 - 注入额外数据到页面里 (如 GraphQL 查询) 重写的话,新建`./pages/_app.js`文件,重写 App 模块如下所示: ```js 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 } } ``` ### 自定义 ``

Examples

- 在服务端呈现 - 初始化服务端时添加文档标记元素 - 通常实现服务端渲染会使用一些 css-in-js 库,如[styled-components](./examples/with-styled-components), [glamorous](./examples/with-glamorous) 或 [emotion](with-emotion)。[styled-jsx](https://github.com/zeit/styled-jsx)是 Next.js 自带默认使用的 css-in-js 库 `Next.js`会自动定义文档标记,比如,你从来不需要添加``, ``等。如果想自定义文档标记,你可以新建`./pages/_document.js`,然后扩展`Document`类: ```jsx // _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 (
) } } ``` 钩子[`getInitialProps`](#fetching-data-and-component-lifecycle)接收到的参数`ctx`对象都是一样的 - 回调函数`renderPage`是会执行 React 渲染逻辑的函数(同步),这种做法有助于此函数支持一些类似于 Aphrodite 的 renderStatic 等一些服务器端渲染容器。 __注意:`
`外的 React 组件将不会渲染到浏览器中,所以那添加应用逻辑代码。如果你页面需要公共组件(菜单或工具栏),可以参照上面说的`App`组件代替。__ ### 自定义错误处理 404和500错误客户端和服务端都会通过`error.js`组件处理。如果你想改写它,则新建`_error.js`在文件夹中: ```jsx import React from 'react' export default class Error extends React.Component { static getInitialProps({ res, err }) { const statusCode = res ? res.statusCode : err ? err.statusCode : null; return { statusCode } } render() { return (

{this.props.statusCode ? `An error ${this.props.statusCode} occurred on server` : 'An error occurred on client'}

) } } ``` ### 渲染内置错误页面 如果你想渲染内置错误页面,你可以使用`next/error`: ```jsx import React from 'react' import Error from 'next/error' import fetch from 'isomorphic-unfetch' export default class Page extends React.Component { static async getInitialProps() { const res = await fetch('https://api.github.com/repos/zeit/next.js') const statusCode = res.statusCode > 200 ? res.statusCode : false const json = await res.json() return { statusCode, stars: json.stargazers_count } } render() { if (this.props.statusCode) { return } return (
Next stars: {this.props.stars}
) } } ``` > 如果你自定义了个错误页面,你可以引入自己的错误页面来代替`next/error` ### 自定义配置 如果你想自定义 Next.js 的高级配置,可以在根目录下新建`next.config.js`文件(与`pages/` 和 `package.json`一起) 注意:`next.config.js`是一个 Node.js 模块,不是一个 JSON 文件,可以用于 Next 启动服务已经构建阶段,但是不作用于浏览器端。 ```js // next.config.js module.exports = { /* config options here */ } ``` 或使用一个函数: ```js module.exports = (phase, {defaultConfig}) => { // // https://github.com/zeit/ return { /* config options here */ } } ``` `phase`是配置文件被加载时的当前内容。你可看到所有的 phases 常量:[constants](./lib/constants.js) 这些常量可以通过`next/constants`引入: ```js const {PHASE_DEVELOPMENT_SERVER} = require('next/constants') module.exports = (phase, {defaultConfig}) => { if(phase === PHASE_DEVELOPMENT_SERVER) { return { /* development only config options here */ } } return { /* config options for all phases except development here */ } } ``` #### 设置自定义构建目录 你可以自定义一个构建目录,如新建`build`文件夹来代替`.next` 文件夹成为构建目录。如果没有配置构建目录,构建时将会自动新建`.next`文件夹 ```js // next.config.js module.exports = { distDir: 'build' } ``` #### 禁止 etag 生成 你可以禁止 etag 生成根据你的缓存策略。如果没有配置,Next 将会生成 etags 到每个页面中。 ```js // next.config.js module.exports = { generateEtags: false } ``` #### 配置 onDemandEntries Next 暴露一些选项来给你控制服务器部署以及缓存页面: ```js module.exports = { onDemandEntries: { // period (in ms) where the server will keep pages in the buffer maxInactiveAge: 25 * 1000, // number of pages that should be kept simultaneously without being disposed pagesBufferLength: 2, } } ``` 这个只是在开发环境才有的功能。如果你在生成环境中想缓存 SSR 页面,请查看[SSR-caching](https://github.com/zeit/next.js/tree/canary/examples/ssr-caching) #### 配置页面后缀名解析扩展 如 typescript 模块[`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript),需要支持解析后缀名为`.ts`的文件。`pageExtensions` 允许你扩展后缀名来解析各种 pages 下的文件。 ```js // next.config.js module.exports = { pageExtensions: ['jsx', 'js'] } ``` #### 配置构建 ID Next.js 使用构建时生成的常量来标识你的应用服务是哪个版本。在每台服务器上运行构建命令时,可能会导致多服务器部署出现问题。为了保持同一个构建 ID,可以配置`generateBuildId`函数: ```js // next.config.js module.exports = { generateBuildId: async () => { // For example get the latest git commit hash here return 'my-build-id' } } ``` ### 自定义 webpack 配置

Examples

可以使用些一些常见的模块 - [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css) - [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass) - [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less) - [@zeit/next-preact](https://github.com/zeit/next-plugins/tree/master/packages/next-preact) - [@zeit/next-typescript](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript) *注意: `webpack`方法将被执行两次,一次在服务端一次在客户端。你可以用`isServer`属性区分客户端和服务端来配置* 多配置可以组合在一起,如: ```js const withTypescript = require('@zeit/next-typescript') const withSass = require('@zeit/next-sass') module.exports = withTypescript(withSass({ webpack(config, options) { // Further custom configuration here return config } })) ``` 为了扩展`webpack`使用,可以在`next.config.js`定义函数。 ```js // next.config.js is not transformed by Babel. So you can only use javascript features supported by your version of Node.js. module.exports = { webpack: (config, { buildId, dev, isServer, defaultLoaders }) => { // Perform customizations to webpack config // Important: return the modified config return config }, webpackDevMiddleware: config => { // Perform customizations to webpack dev middleware config // Important: return the modified config return config } } ``` `webpack`的第二个参数是个对象,你可以自定义配置它,对象属性如下所示: - `buildId` - 字符串类型,构建的唯一标示 - `dev` - `Boolean`型,判断你是否在开发环境下 - `isServer` - `Boolean` 型,为`true`使用在服务端, 为`false`使用在客户端. - `defaultLoaders` - 对象型 ,内部加载器, 你可以如下配置 - `babel` - 对象型,配置`babel-loader`. - `hotSelfAccept` - 对象型, `hot-self-accept-loader`配置选项.这个加载器只能用于高阶案例。如 [`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript)添加顶层 typescript 页面。 `defaultLoaders.babel`使用案例如下: ```js // Example next.config.js for adding a loader that depends on babel-loader // This source was taken from the @zeit/next-mdx plugin source: // https://github.com/zeit/next-plugins/blob/master/packages/next-mdx module.exports = { webpack: (config, {}) => { config.module.rules.push({ test: /\.mdx/, use: [ options.defaultLoaders.babel, { loader: '@mdx-js/loader', options: pluginOptions.options } ] }) return config } } ``` ### 自定义 babel 配置

Examples

为了扩展方便我们使用`babel`,可以在应用根目录新建`.babelrc`文件,该文件可配置。 如果有该文件,我们将会考虑数据源,因此也需要定义 next 项目需要的东西,也就是 `next/babel`预设。 这种设计方案将会使你不诧异于我们可以定制 babel 配置。 下面是`.babelrc`文件案例: ```json { "presets": ["next/babel"], "plugins": [] } ``` `next/babel`预设可处理各种 React 应用所需要的情况。包括: - preset-env - preset-react - plugin-proposal-class-properties - plugin-proposal-object-rest-spread - plugin-transform-runtime - styled-jsx presets / plugins 不允许添加到`.babelrc`中,然而你可以配置`next/babel`预设: ```json { "presets": [ ["next/babel", { "preset-env": {}, "transform-runtime": {}, "styled-jsx": {}, "class-properties": {} }] ], "plugins": [] } ``` `"preset-env"`模块选项应该保持为 false,否则 webpack 代码分割将被禁用。 ### 暴露配置到服务端和客户端 `next/config`模块使你应用运行时可以读取些存储在`next.config.js`的配置项。`serverRuntimeConfig`属性只在服务器端可用,`publicRuntimeConfig`属性在服务端和客户端可用。 ```js // next.config.js module.exports = { serverRuntimeConfig: { // Will only be available on the server side mySecret: 'secret' }, publicRuntimeConfig: { // Will be available on both server and client staticFolder: '/static', mySecret: process.env.MY_SECRET // Pass through env variables } } ``` ```js // pages/index.js import getConfig from 'next/config' // Only holds serverRuntimeConfig and publicRuntimeConfig from next.config.js nothing else. const {serverRuntimeConfig, publicRuntimeConfig} = getConfig() console.log(serverRuntimeConfig.mySecret) // Will only be available on the server side console.log(publicRuntimeConfig.staticFolder) // Will be available on both server and client export default () =>
logo
``` ### 启动服务选择 hostname 启动开发环境服务可以设置不同的 hostname,你可以在启动命令后面加上`--hostname 主机名` 或 `-H 主机名`。它将会启动一个 TCP 服务器来监听连接所提供的主机。 ### CDN 支持前缀 建立一个 CDN,你能配置`assetPrefix`选项,去配置你的 CDN 源。 ```js const isProd = process.env.NODE_ENV === 'production' module.exports = { // You may only need to add assetPrefix in the production. assetPrefix: isProd ? 'https://cdn.mydomain.com' : '' } ``` 注意:Next.js 运行时将会自动添加前缀,但是对于`/static`是没有效果的,如果你想这些静态资源也能使用 CDN,你需要自己添加前缀。有一个方法可以判断你的环境来加前缀,如 [in this example](https://github.com/zeit/next.js/tree/master/examples/with-universal-configuration)。 ## 项目部署 部署中,你可以先构建打包生成环境代码,再启动服务。因此,构建和启动分为下面两条命令: ```bash next build next start ``` 例如,使用[`now`](https://zeit.co/now)去部署`package.json`配置文件如下: ```json { "name": "my-app", "dependencies": { "next": "latest" }, "scripts": { "dev": "next", "build": "next build", "start": "next start" } } ``` 然后就可以直接运行`now`了。 Next.js 也有其他托管解决方案。请查考 wiki 章节['Deployment'](https://github.com/zeit/next.js/wiki/Deployment) 。 注意:`NODE_ENV`可以通过`next`命令配置,如果没有配置,会最大渲染,如果你使用编程式写法的话[programmatically](#custom-server-and-routing),你需要手动设置`NODE_ENV=production`。 注意:推荐将`.next`或自定义打包文件夹[custom dist folder](https://github.com/zeit/next.js#custom-configuration)放入`.gitignore` 或 `.npmignore`中。否则,使用`files` 或 `now.files` 添加部署白名单,并排除`.next`或自定义打包文件夹。 ## 浏览器支持 Next.js 支持 IE11 和所有的现代浏览器使用了[`@babel/preset-env`](https://new.babeljs.io/docs/en/next/babel-preset-env.html)。为了支持 IE11,Next.js 需要全局添加`Promise`的 polyfill。有时你的代码或引入的其他 NPM 包的部分功能现代浏览器不支持,则需要用 polyfills 去实现。 ployflls 实现案例为[polyfills](https://github.com/zeit/next.js/tree/canary/examples/with-polyfills)。 ## 导出静态页面

Examples

`next export`可以输出一个 Next.js 应用作为静态资源应用而不依靠 Node.js 服务。 这个输出的应用几乎支持 Next.js 的所有功能,包括动态路由,预获取,预加载以及动态导入。 `next export`将把所有有可能渲染出的 HTML 都生成。这是基于映射对象的`pathname`关键字关联到页面对象。这个映射叫做`exportPathMap`。 页面对象有2个属性: - `page` - 字符串类型,页面生成目录 - `query` - 对象类型,当预渲染时,`query`对象将会传入页面的生命周期`getInitialProps`中。默认为`{}`。 ### 使用 通常开发 Next.js 应用你将会运行: ``` next build next export ``` `next export`命令默认不需要任何配置,将会自动生成默认`exportPathMap`生成`pages`目录下的路由你页面。 如果你想动态配置路由,可以在`next.config.js`中添加异步函数`exportPathMap`。 ```js // next.config.js module.exports = { exportPathMap: async function (defaultPathMap) { return { '/': { page: '/' }, '/about': { page: '/about' }, '/readme.md': { page: '/readme' }, '/p/hello-nextjs': { page: '/post', query: { title: 'hello-nextjs' } }, '/p/learn-nextjs': { page: '/post', query: { title: 'learn-nextjs' } }, '/p/deploy-nextjs': { page: '/post', query: { title: 'deploy-nextjs' } } } } } ``` > 注意:如果 path 的结尾是目录名,则将导出`/dir-name/index.html`,但是如果结尾有扩展名,将会导出对应的文件,如上`/readme.md`。如果你使用`.html`以外的扩展名解析文件时,你需要设置 header 的`Content-Type`头为"text/html". 输入下面命令: ```sh next build next export ``` 你可以在`package.json`添加一个 NPM 脚本,如下所示: ```json { "scripts": { "build": "next build", "export": "npm run build && next export" } } ``` 接着只用执行一次下面命令: ```sh npm run export ``` 然后你将会有一个静态页面应用在`out` 目录下。 > 你也可以自定义输出目录。可以运行`next export -h`命令查看帮助。 现在你可以部署`out`目录到任意静态资源服务器上。注意如果部署 GitHub Pages 需要加个额外的步骤,[文档如下](https://github.com/zeit/next.js/wiki/Deploying-a-Next.js-app-into-GitHub-Pages) 例如,访问`out`目录并用下面命令部署应用[ZEIT Now](https://zeit.co/now). ```sh now ``` ### 限制 使用`next export`,我们创建了个静态 HTML 应用。构建时将会运行页面里生命周期`getInitialProps` 函数。 `req`和`res`只在服务端可用,不能通过`getInitialProps`。 > 所以你不能预构建 HTML 文件时动态渲染 HTML 页面。如果你想动态渲染可以运行`next start`或其他自定义服务端 API。 ## 多 zone

Examples

一个 zone 时一个单独的 Next.js 应用。如果你有很多 zone,你可以合并成一个应用。 例如,你如下有两个 zone: * https://docs.my-app.com 服务于路由 `/docs/**` * https://ui.my-app.com 服务于所有页面 有多 zone 应用技术支持,你可以将几个应用合并到一个,而且可以自定义 URL 路径,使你能同时单独开发各个应用。 > 与 microservices 观念类似, 只是应用于前端应用. ### 怎么定义一个 zone zone 没有单独的 API 文档。你需要做下面事即可: * 确保你的应用里只有需要的页面 (例如, https://ui.my-app.com 不包含 `/docs/**`) * 确保你的应用有个前缀[assetPrefix](https://github.com/zeit/next.js#cdn-support-with-asset-prefix)。(你也可以定义动态前缀[dynamically](https://github.com/zeit/next.js#dynamic-assetprefix)) ### 怎么合并他们 你能使用 HTTP 代理合并 zone 你能使用代理[micro proxy](https://github.com/zeit/micro-proxy)来作为你的本地代理服务。它允许你定义路由规则如下: ```json { "rules": [ {"pathname": "/docs**", "method":["GET", "POST", "OPTIONS"], "dest": "https://docs.my-app.com"}, {"pathname": "/**", "dest": "https://ui.my-app.com"} ] } ``` 生产环境部署,如果你使用了[ZEIT now](https://zeit.co/now),可以它的使用[path alias](https://zeit.co/docs/features/path-aliases) 功能。否则,你可以设置你已使用的代理服务编写上面规则来路由 HTML 页面 ## 技巧 - [设置301重定向](https://www.raygesualdo.com/posts/301-redirects-with-nextjs/) - [只处理服务器端模块](https://arunoda.me/blog/ssr-and-server-only-modules) - [构建项目 React-Material-UI-Next-Express-Mongoose-Mongodb](https://github.com/builderbook/builderbook) - [构建一个 SaaS 产品 React-Material-UI-Next-MobX-Express-Mongoose-MongoDB-TypeScript](https://github.com/async-labs/saas) ## 问答
这个产品可以用于生产环境吗? https://zeit.co 都是一直用 Next.js 写的。 它的开发体验和终端用户体验都很好,所以我们决定开源出来给大家共享。
体积多大? 客户端大小根据应用需求不一样大小也不一样。 一个最简单 Next 应该用 gzip 压缩后大约65kb
这个像 `create-react-app`? 是或不是. 是,因为它让你的 SSR 开发更简单。 不是,因为它规定了一定的目录结构,使我们能做以下更高级的事: - 服务端渲染 - 自动代码分割 此外,Next.js 还提供两个内置特性: - 路由与懒加载组件: `` (通过引入 `next/link`) - 修改``的组件: `` (通过引入 `next/head`) 如果你想写共用组件,可以嵌入 Next.js 应用和 React 应用中,推荐使用`create-react-app`。你可以更改`import`保持代码清晰。
怎么解决 CSS 嵌入 JS 问题? Next.js 自带[styled-jsx](https://github.com/zeit/styled-jsx)库支持 CSS 嵌入 JS。而且你可以选择其他嵌入方法到你的项目中,可参考文档[as mentioned before](#css-in-js)。
哪些语法会被转换?怎么转换它们? 我们遵循 V8 引擎的,如今 V8 引擎广泛支持 ES6 语法以及`async`和`await`语法,所以我们支持转换它们。但是 V8 引擎不支持修饰器语法,所以我们也不支持转换这语法。 可以参照[这些](https://github.com/zeit/next.js/blob/master/server/build/webpack.js#L79) 以及 [这些](https://github.com/zeit/next.js/issues/26)
为什么使用新路由? Next.js 的特别之处如下所示: - 路由不需要被提前知道 - 路由总是被懒加载 - 顶层组件可以定义生命周期`getInitialProps`来阻止路由加载(当服务端渲染或路由懒加载时) 因此,我们可以介绍一个非常简单的路由方法,它由下面两部分组成: - 每个顶层组件都将会收到一个`url`对象,来检查 url 或修改历史记录 - ``组件用于包装如(``)标签的元素容器,来执行客户端转换。 我们使用了些有趣的场景来测试路由的灵活性,例如,可查看[nextgram](https://github.com/zeit/nextgram)。
我怎么定义自定义路由? 我们通过请求处理来[添加](#custom-server-and-routing)任意 URL 与任意组件之前的映射关系。 在客户端,我们``组件有个属性`as`,可以装饰改变获取到的 URL。
怎么获取数据? 这由你决定。`getInitialProps`是一个异步函数`async`(也就是函数将会返回个`Promise`)。你可以在任意位置获取数据。
我可以使用 GraphQL 吗? 是的! 这里有个例子[Apollo](./examples/with-apollo).
我可以使用 Redux 吗? 是的! 这里有个[例子](./examples/with-redux)
我可以在 Next 应用中使用我喜欢的 Javascript 库或工具包吗? 从我们第一次发版就已经提供**很多**例子,你可以查看这些[例子](./examples)。
什么启发我们做这个? 我们实现的大部分目标都是通过 Guillermo Rauch 的[Web 应用的7原则](http://rauchg.com/2014/7-principles-of-rich-web-applications/)来启发出的。 PHP 的易用性也是个很好的灵感来源,我们觉得 Next.js 可以替代很多需要用 PHP 输出 HTML 的场景。 与 PHP 不同的是,我们得利于 ES6 模块系统,每个文件会输出一个**组件或方法**,以便可以轻松的导入用于懒加载和测试 我们研究 React 的服务器渲染时并没有花费很大的步骤,因为我们发现一个类似于 Next.js 的产品,React 作者 Jordan Walke 写的[react-page](https://github.com/facebookarchive/react-page) (现在已经废弃)
## 贡献 可查看 [contributing.md](./contributing.md) ## 作者 - Arunoda Susiripala ([@arunoda](https://twitter.com/arunoda)) – [ZEIT](https://zeit.co) - Tim Neutkens ([@timneutkens](https://twitter.com/timneutkens)) – [ZEIT](https://zeit.co) - Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) – [ZEIT](https://zeit.co) - Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) – [ZEIT](https://zeit.co) - Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) – [ZEIT](https://zeit.co) - Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) – Knight-Mozilla / Coral Project