[](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 {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` - 获取响应对象（仅限客户端）
- `err` - 渲染过程中的任何错误
### 路由
Next.js不会随应用程序中每个可能的路由一起发布路由清单，因此当前页面不知道客户端上的任何其他页面。出于可扩展性考虑，所有后续路由都会惰性加载。
#### ``用法
Examples
Click{' '}
here
{' '}
to read more
)
}
export default Home
```
```jsx
// pages/about.js
function About() {
return Welcome to About!
} export default About ``` **自定义路由 (使用URL中的props)** `` 组件有两个主要属性: - `href`: `pages`目录内的路径+查询字符串. - `as`: 将在浏览器URL栏中呈现的路径. 例子: 1. 假设你有个这样的路由 `/post/:slug`. 2. 你可以创建文件 `pages/post.js` ```jsx class Post extends React.Component { static async getInitialProps({ query }) { console.log('SLUG', query.slug) return {} } render() { returnMy blog post
} } export default Post ``` 3. 将路由添加到 `express` (或者其他服务端) 的 `server.js` 文件 (这仅适用于SSR). 这将解析`/post/:slug`到`pages/post.js`并在getInitialProps中提供`slug`作为查询的一部分。 ```jsx server.get('/post/:slug', (req, res) => { return app.render(req, res, '/post', { slug: req.params.slug }) }) ``` 4. 对于客户端路由，使用 `next/link`: ```jsx ``` _注意：可以使用[``](#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调用`pushState`
- `replace(url, as=url)` - 用给定的url调用`replaceState`
- `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);
```
如果路由加载被取消（比如快速连续双击链接），`routeChangeError`将触发。传递err,并且属性cancelled的值为true。
```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) { returnNext 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
The value of customKey is: {process.env.customKey}
} export default Index ``` #### 运行时配置 > ⚠️ 请注意，使用此选项时不可用 `target: 'serverless'` > ⚠️ 通常，您希望使用构建时配置来提供配置。原因是运行时配置增加了一个小的rendering/initialization开销。 `next/config`模块使你应用运行时可以读取些存储在`next.config.js`的配置项。`serverRuntimeConfig`属性只在服务器端可用，`publicRuntimeConfig`属性在服务端和客户端可用。 ```js // next.config.js module.exports = { serverRuntimeConfig: { // Will only be available on the server side mySecret: 'secret', secondSecret: process.env.SECOND_SECRET // Pass through env variables }, publicRuntimeConfig: { // Will be available on both server and client staticFolder: '/static' } } ``` ```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 function MyImage() { return (
例子
- now.sh
- anna-artemov.now.sh
- 我们鼓励为本节提供更多示例
Examples
Examples