[](https://www.npmjs.com/package/next)
[](https://travis-ci.org/zeit/next.js)
[](https://ci.appveyor.com/project/arunoda/next-js/branch/master)
[](https://coveralls.io/r/zeit/next.js?branch=master)
[](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)
- [自定义 `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
#### 支持嵌入样式
案例
Hello world
```
想查看更多案例可以点击 [styled-jsx documentation](https://www.npmjs.com/package/styled-jsx)查看.
#### 内嵌样式
scoped!
有些情况可以使用 CSS 内嵌 JS 写法。如下所示： ```jsx export default () =>
hi there
``` 更复杂的内嵌样式解决方案，特别是服务端渲染的时样式更改。我们可以通过包裹自定义 Document，来添加样式，案例如下：[custom `
```
_注意：不要自定义静态文件夹的名字，只能叫`static` ，因为只有这个名字 Next.js 才会把它当作静态资源。
### 生成``
``
Examples
Hello world!
Hello world!
Examples
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
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
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{' '}
```
##### 暴露 `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 }) =>
你也可以用`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
Examples
Examples
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 (
)
}
}
export default withRouter(MyLink)
```
### 自定义服务端路由
一般你使用`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
HOME PAGE is here!
...
} ) export default () =>HOME PAGE is here!
HOME PAGE is here!
{props.title}
组件来初始化页面。你可以重写它来控制页面初始化，如下面的事： - 当页面变化时保持页面布局 - 当路由变化时保持页面状态 - 使用`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
- 在服务端呈现 - 初始化服务端时添加文档标记元素 - 通常实现服务端渲染会使用一些 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 (
{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
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
Examples
Examples
Examples