From 3e9e25191d8cd41f979f27ea9287fa4cc3798369 Mon Sep 17 00:00:00 2001 From: ULIVZ <472590061@qq.com> Date: Thu, 16 Aug 2018 22:53:01 +0800 Subject: [PATCH 1/2] fix: link refernece warning --- docs/README.md | 2 +- docs/ja/README.md | 4 ++-- docs/ru/README.md | 2 +- docs/zh/README.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/README.md b/docs/README.md index 01d42aab..d5792e8a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,7 @@ This guide requires the following minimum versions of Vue and supporting librari - vue-router 2.5.0+ - vue-loader 12.0.0+ & vue-style-loader 3.0.0+ -If you have previously used Vue 2.2 with SSR, you will notice that the recommended code structure is now [a bit different](./guide/structure.md) (with the new [runInNewContext](./api/#runinnewcontext) option set to `false`). Your existing app should continue to work, but it's recommended to migrate to the new recommendations. +If you have previously used Vue 2.2 with SSR, you will notice that the recommended code structure is now [a bit different](./guide/structure.md) (with the new [runInNewContext](./api/README.md#runinnewcontext) option set to `false`). Your existing app should continue to work, but it's recommended to migrate to the new recommendations. ::: ## What is Server-Side Rendering (SSR)? diff --git a/docs/ja/README.md b/docs/ja/README.md index c6e34274..d221fc79 100644 --- a/docs/ja/README.md +++ b/docs/ja/README.md @@ -5,7 +5,7 @@ > - vue-router 2.5.0 以上 > - vue-loader 12.0.0 以上 & vue-style-loader 3.0.0 以上 -> もし以前に、 SSR で Vue 2.2 を使用していた場合、 推奨されるコードの構造が[少しだけ違うこと](./structure.md)に気がつくでしょう (新しいオプションの [runInNewContext](./api.md#runinnewcontext) を `false` にしている場合)。あなたの既存のアプリケーションは依然として動作はするでしょうが、新しく推奨される方に移行されることをオススメします。 +> もし以前に、 SSR で Vue 2.2 を使用していた場合、 推奨されるコードの構造が[少しだけ違うこと](./guide/structure.md)に気がつくでしょう (新しいオプションの [runInNewContext](./api/README.md#runinnewcontext) を `false` にしている場合)。あなたの既存のアプリケーションは依然として動作はするでしょうが、新しく推奨される方に移行されることをオススメします。 ## サーバサイドレンダリング (SSR) とは何か? @@ -41,7 +41,7 @@ SSR を使用する際に考慮すべきトレードオフも何点かありま ## このガイドについて -このガイドはサーバとして Node.js を使用してサーバで描画されたシングルページアプリケーションに焦点が当てられています。他のバックエンドの設定と Vue の SSR と混在させることは、それ自体主題であり、[専用セクション](./non-node.md)で手短に議論されています。 +このガイドはサーバとして Node.js を使用してサーバで描画されたシングルページアプリケーションに焦点が当てられています。他のバックエンドの設定と Vue の SSR と混在させることは、それ自体主題であり、[専用セクション](./guide/non-node.md)で手短に議論されています。 このガイドは、Vue.js 自体に精通しており、且つ Node.js と webpack に関する実用的な知識を持っていることを前提としています。もしあなたが、すぐに使用できる高度なソリューションを求めている場合は、[Nuxt.js](http://nuxtjs.org/) を試してみてください。これは同じ Vue スタック上に構築されていますが、多くの定型文が抽象化されており、静的なサイト生成などの追加機能を提供します。しかし、アプリケーションの構造をより直接的に制御する必要がある場合は、ユースケースに合わない場合があります。いずれにしても、仕組みをより理解するために、このガイドを読むことはまだ有益です。 diff --git a/docs/ru/README.md b/docs/ru/README.md index 62da90c0..3d8185f5 100644 --- a/docs/ru/README.md +++ b/docs/ru/README.md @@ -7,7 +7,7 @@ - vue-router 2.5.0+ - vue-loader 12.0.0+ & vue-style-loader 3.0.0+ -Если вы ранее использовали Vue 2.2 с серверным рендерингом, вы заметите, что рекомендуемая структура кода теперь [немного отличается](./guide/structure.md) (с новой опцией [runInNewContext](./api/#runinnewcontext), установленной в `false`). Ваше существующее приложение по-прежнему будет работать, но лучше внесите изменения с учётом новых рекомендаций. +Если вы ранее использовали Vue 2.2 с серверным рендерингом, вы заметите, что рекомендуемая структура кода теперь [немного отличается](./guide/structure.md) (с новой опцией [runInNewContext](./api/README.md#runinnewcontext), установленной в `false`). Ваше существующее приложение по-прежнему будет работать, но лучше внесите изменения с учётом новых рекомендаций. ::: ## Что такое серверный рендеринг (SSR)? diff --git a/docs/zh/README.md b/docs/zh/README.md index 95e851d2..9b1d1c99 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -6,7 +6,7 @@ - vue-router 2.5.0+ - vue-loader 12.0.0+ & vue-style-loader 3.0.0+ -如果先前已经使用过 Vue 2.2 的服务器端渲染(SSR)，你应该注意到，推荐的代码结构现在[略有不同](./guide/structure.md)（使用新的 [runInNewContext](./api/#runinnewcontext) 选项，并设置为 `false`）。现有的应用程序可以继续运行，但建议你迁移到新的推荐规范。 +如果先前已经使用过 Vue 2.2 的服务器端渲染(SSR)，你应该注意到，推荐的代码结构现在[略有不同](./guide/structure.md)（使用新的 [runInNewContext](./api/README.md#runinnewcontext) 选项，并设置为 `false`）。现有的应用程序可以继续运行，但建议你迁移到新的推荐规范。 ::: ## 什么是服务器端渲染(SSR)？ From c95fd4b3eb56aceef7180a18e222b137860e6afa Mon Sep 17 00:00:00 2001 From: ULIVZ <472590061@qq.com> Date: Thu, 16 Aug 2018 23:13:58 +0800 Subject: [PATCH 2/2] chore: fix Chinese docs format --- docs/zh/README.md | 26 +++++++++++++------------- docs/zh/api/README.md | 26 +++++++++++++------------- docs/zh/guide/README.md | 2 +- docs/zh/guide/build-config.md | 28 ++++++++++++++-------------- docs/zh/guide/bundle-renderer.md | 2 +- docs/zh/guide/caching.md | 14 +++++++------- docs/zh/guide/data.md | 20 ++++++++++---------- docs/zh/guide/head.md | 6 +++--- docs/zh/guide/hydration.md | 6 +++--- docs/zh/guide/routing.md | 4 ++-- docs/zh/guide/streaming.md | 8 ++++---- docs/zh/guide/structure.md | 6 +++--- docs/zh/guide/universal.md | 14 +++++++------- 13 files changed, 81 insertions(+), 81 deletions(-) diff --git a/docs/zh/README.md b/docs/zh/README.md index 9b1d1c99..aec1107f 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -6,44 +6,44 @@ - vue-router 2.5.0+ - vue-loader 12.0.0+ & vue-style-loader 3.0.0+ -如果先前已经使用过 Vue 2.2 的服务器端渲染(SSR)，你应该注意到，推荐的代码结构现在[略有不同](./guide/structure.md)（使用新的 [runInNewContext](./api/README.md#runinnewcontext) 选项，并设置为 `false`）。现有的应用程序可以继续运行，但建议你迁移到新的推荐规范。 +如果先前已经使用过 Vue 2.2 的服务器端渲染 (SSR)，你应该注意到，推荐的代码结构现在[略有不同](./guide/structure.md)（使用新的 [runInNewContext](./api/README.md#runinnewcontext) 选项，并设置为 `false`）。现有的应用程序可以继续运行，但建议你迁移到新的推荐规范。 ::: -## 什么是服务器端渲染(SSR)？ +## 什么是服务器端渲染 (SSR)？ Vue.js 是构建客户端应用程序的框架。默认情况下，可以在浏览器中输出 Vue 组件，进行生成 DOM 和操作 DOM。然而，也可以将同一个组件渲染为服务器端的 HTML 字符串，将它们直接发送到浏览器，最后将这些静态标记"激活"为客户端上完全可交互的应用程序。 服务器渲染的 Vue.js 应用程序也可以被认为是"同构"或"通用"，因为应用程序的大部分代码都可以在**服务器**和**客户端**上运行。 -## 为什么使用服务器端渲染(SSR)？ +## 为什么使用服务器端渲染 (SSR)？ -与传统 SPA（Single-Page Application - 单页应用程序）相比，服务器端渲染(SSR)的优势主要在于： +与传统 SPA (单页应用程序 (Single-Page Application)) 相比，服务器端渲染 (SSR) 的优势主要在于： - 更好的 SEO，由于搜索引擎爬虫抓取工具可以直接查看完全渲染的页面。 请注意，截至目前，Google 和 Bing 可以很好对同步 JavaScript 应用程序进行索引。在这里，同步是关键。如果你的应用程序初始展示 loading 菊花图，然后通过 Ajax 获取内容，抓取工具并不会等待异步完成后再行抓取页面内容。也就是说，如果 SEO 对你的站点至关重要，而你的页面又是异步获取内容，则你可能需要服务器端渲染(SSR)解决此问题。 -- 更快的内容到达时间(time-to-content)，特别是对于缓慢的网络情况或运行缓慢的设备。无需等待所有的 JavaScript 都完成下载并执行，才显示服务器渲染的标记，所以你的用户将会更快速地看到完整渲染的页面。通常可以产生更好的用户体验，并且对于那些「内容到达时间(time-to-content)与转化率直接相关」的应用程序而言，服务器端渲染(SSR)至关重要。 +- 更快的内容到达时间 (time-to-content)，特别是对于缓慢的网络情况或运行缓慢的设备。无需等待所有的 JavaScript 都完成下载并执行，才显示服务器渲染的标记，所以你的用户将会更快速地看到完整渲染的页面。通常可以产生更好的用户体验，并且对于那些「内容到达时间(time-to-content) 与转化率直接相关」的应用程序而言，服务器端渲染 (SSR) 至关重要。 -使用服务器端渲染(SSR)时还需要有一些权衡之处： +使用服务器端渲染 (SSR) 时还需要有一些权衡之处： -- 开发条件所限。浏览器特定的代码，只能在某些生命周期钩子函数(lifecycle hook)中使用；一些外部扩展库(external library)可能需要特殊处理，才能在服务器渲染应用程序中运行。 +- 开发条件所限。浏览器特定的代码，只能在某些生命周期钩子函数 (lifecycle hook) 中使用；一些外部扩展库 (external library) 可能需要特殊处理，才能在服务器渲染应用程序中运行。 -- 涉及构建设置和部署的更多要求。与可以部署在任何静态文件服务器上的完全静态单页面应用程序(SPA)不同，服务器渲染应用程序，需要处于 Node.js server 运行环境。 +- 涉及构建设置和部署的更多要求。与可以部署在任何静态文件服务器上的完全静态单页面应用程序 (SPA) 不同，服务器渲染应用程序，需要处于 Node.js server 运行环境。 -- 更多的服务器端负载。在 Node.js 中渲染完整的应用程序，显然会比仅仅提供静态文件的 server 更加大量占用 CPU 资源(CPU-intensive - CPU 密集)，因此如果你预料在高流量环境(high traffic)下使用，请准备相应的服务器负载，并明智地采用缓存策略。 +- 更多的服务器端负载。在 Node.js 中渲染完整的应用程序，显然会比仅仅提供静态文件的 server 更加大量占用 CPU 资源 (CPU-intensive - CPU 密集)，因此如果你预料在高流量环境 (high traffic) 下使用，请准备相应的服务器负载，并明智地采用缓存策略。 -在对你的应用程序使用服务器端渲染(SSR)之前，你应该问的第一个问题是，是否真的需要它。这主要取决于内容到达时间(time-to-content)对应用程序的重要程度。例如，如果你正在构建一个内部仪表盘，初始加载时的额外几百毫秒并不重要，这种情况下去使用服务器端渲染(SSR)将是一个小题大作之举。然而，内容到达时间(time-to-content)要求是绝对关键的指标，在这种情况下，服务器端渲染(SSR)可以帮助你实现最佳的初始加载性能。 +在对你的应用程序使用服务器端渲染 (SSR) 之前，你应该问的第一个问题是，是否真的需要它。这主要取决于内容到达时间 (time-to-content) 对应用程序的重要程度。例如，如果你正在构建一个内部仪表盘，初始加载时的额外几百毫秒并不重要，这种情况下去使用服务器端渲染 (SSR) 将是一个小题大作之举。然而，内容到达时间 (time-to-content) 要求是绝对关键的指标，在这种情况下，服务器端渲染 (SSR) 可以帮助你实现最佳的初始加载性能。 -## 服务器端渲染 vs 预渲染(SSR vs Prerendering) +## 服务器端渲染 vs 预渲染 (SSR vs Prerendering) -如果你调研服务器端渲染(SSR)只是用来改善少数营销页面（例如 `/`, `/about`, `/contact` 等）的 SEO，那么你可能需要**预渲染**。无需使用 web 服务器实时动态编译 HTML，而是使用预渲染方式，在构建时(build time)简单地生成针对特定路由的静态 HTML 文件。优点是设置预渲染更简单，并可以将你的前端作为一个完全静态的站点。 +如果你调研服务器端渲染 (SSR) 只是用来改善少数营销页面（例如 `/`, `/about`, `/contact` 等）的 SEO，那么你可能需要**预渲染**。无需使用 web 服务器实时动态编译 HTML，而是使用预渲染方式，在构建时 (build time) 简单地生成针对特定路由的静态 HTML 文件。优点是设置预渲染更简单，并可以将你的前端作为一个完全静态的站点。 如果你使用 webpack，你可以使用 [prerender-spa-plugin](https://github.com/chrisvfritz/prerender-spa-plugin) 轻松地添加预渲染。它已经被 Vue 应用程序广泛测试 - 事实上，[作者](https://github.com/chrisvfritz)是 Vue 核心团队的成员。 ## 关于此指南 -本指南专注于，使用 Node.js server 的服务器端单页面应用程序渲染。将 Vue 服务器端渲染(SSR)与其他后端设置进行混合使用，是后端自身集成 SSR 的话题，我们会在 [专门章节](./guide/non-node.md) 中进行简要讨论。 +本指南专注于，使用 Node.js server 的服务器端单页面应用程序渲染。将 Vue 服务器端渲染 (SSR) 与其他后端设置进行混合使用，是后端自身集成 SSR 的话题，我们会在 [专门章节](./guide/non-node.md) 中进行简要讨论。 本指南将会非常深入，并且假设你已经熟悉 Vue.js 本身，并且具有 Node.js 和 webpack 的相当不错的应用经验。如果你倾向于使用提供了平滑开箱即用体验的更高层次解决方案，你应该去尝试使用 [Nuxt.js](https://nuxtjs.org/)。它建立在同等的 Vue 技术栈之上，但抽象出很多模板，并提供了一些额外的功能，例如静态站点生成。但是，如果你需要更直接地控制应用程序的结构，Nuxt.js 并不适合这种使用场景。无论如何，阅读本指南将更有助于更好地了解一切如何运行。 diff --git a/docs/zh/api/README.md b/docs/zh/api/README.md index 63f314f2..a69414db 100644 --- a/docs/zh/api/README.md +++ b/docs/zh/api/README.md @@ -42,7 +42,7 @@ const renderer = createBundleRenderer(serverBundle, { /* 选项 */ }) renderer.renderToString(vm, context?, callback?): ?Promise ``` -将 Vue 实例渲染为字符串。上下文对象(context object)可选。回调函数是典型的 Node.js 风格回调，其中第一个参数是可能抛出的错误，第二个参数是渲染完毕的字符串。 +将 Vue 实例渲染为字符串。上下文对象 (context object) 可选。回调函数是典型的 Node.js 风格回调，其中第一个参数是可能抛出的错误，第二个参数是渲染完毕的字符串。 在 2.5.0+ 版本中，此 callback 回调函数是可选项。在不传递 callback 时，此方法返回一个 Promise 对象，在其 resolve 后返回最终渲染的 HTML。 @@ -54,7 +54,7 @@ renderer.renderToString(vm, context?, callback?): ?Promise renderer.renderToStream(vm[, context]): stream.Readable ``` -将 Vue 实例渲染为一个 [Node.js 可读流](https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_readable_streams)。上下文对象(context object)可选。更多细节请查看[流式渲染](../guide/streaming.md)。 +将 Vue 实例渲染为一个 [Node.js 可读流](https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_readable_streams)。上下文对象 (context object) 可选。更多细节请查看[流式渲染](../guide/streaming.md)。 ## Class: BundleRenderer @@ -66,7 +66,7 @@ renderer.renderToStream(vm[, context]): stream.Readable bundleRenderer.renderToString([context, callback]): ?Promise ``` -将 bundle 渲染为字符串。上下文对象(context object)可选。回调是一个典型的 Node.js 风格回调，其中第一个参数是可能抛出的错误，第二个参数是渲染完毕的字符串。 +将 bundle 渲染为字符串。上下文对象 (context object) 可选。回调是一个典型的 Node.js 风格回调，其中第一个参数是可能抛出的错误，第二个参数是渲染完毕的字符串。 在 2.5.0+ 版本中，此 callback 回调函数是可选项。在不传递 callback 时，此方法返回一个 Promise 对象，在其 resolve 后返回最终渲染的 HTML。 @@ -78,7 +78,7 @@ bundleRenderer.renderToString([context, callback]): ?Promise bundleRenderer.renderToStream([context]): stream.Readable ``` -将 bundle 渲染为一个 [Node.js 可读流](https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_readable_streams)。上下文对象(context object)可选。更多细节请查看[流式渲染](../guide/streaming.md)。 +将 bundle 渲染为一个 [Node.js 可读流](https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_readable_streams)。上下文对象 (context object) 可选。更多细节请查看[流式渲染](../guide/streaming.md)。 ## Renderer 选项 @@ -86,25 +86,25 @@ bundleRenderer.renderToStream([context]): stream.Readable 为整个页面的 HTML 提供一个模板。此模板应包含注释 ``，作为渲染应用程序内容的占位符。 -模板还支持使用渲染上下文(render context)进行基本插值： +模板还支持使用渲染上下文 (render context) 进行基本插值： -- 使用双花括号(double-mustache)进行 HTML 转义插值(HTML-escaped interpolation)； -- 使用三花括号(triple-mustache)进行 HTML 不转义插值(non-HTML-escaped interpolation)。 +- 使用双花括号 (double-mustache) 进行 HTML 转义插值 (HTML-escaped interpolation)； +- 使用三花括号 (triple-mustache) 进行 HTML 不转义插值 (non-HTML-escaped interpolation)。 -当在渲染上下文(render context)上存在一些特定属性时，模板会自动注入对应的内容： +当在渲染上下文 (render context) 上存在一些特定属性时，模板会自动注入对应的内容： -- `context.head`：（字符串）将会被作为 HTML 注入到页面的头部(head)里。 +- `context.head`：（字符串）将会被作为 HTML 注入到页面的头部 (head) 里。 - `context.styles`：（字符串）内联 CSS，将以 style 标签的形式注入到页面头部。注意，如过你使用了 `vue-loader` + `vue-style-loader` 来处理组件 CSS，此属性会在构建过程中被自动生成。 - `context.state`：（对象）初始 Vuex store 状态，将以 `window.__INITIAL_STATE__` 的形式内联到页面。内联的 JSON 将使用 [serialize-javascript](https://github.com/yahoo/serialize-javascript) 自动清理，以防止 XSS 攻击。 - 在 2.5.0+ 版本中，嵌入式 script 也可以也可以在生产模式(production mode)下自行移除。 + 在 2.5.0+ 版本中，嵌入式 script 也可以也可以在生产模式 (production mode) 下自行移除。 此外，当提供 `clientManifest` 时，模板会自动注入以下内容： - 渲染当前页面所需的最优客户端 JavaScript 和 CSS 资源（支持自动推导异步代码分割所需的文件）； -- 为要渲染页面提供最佳的 `` 资源提示(resource hints)。 +- 为要渲染页面提供最佳的 `` 资源提示 (resource hints)。 你也可以通过将 `inject: false` 传递给 renderer，来禁用所有自动注入。 @@ -125,7 +125,7 @@ bundleRenderer.renderToStream([context]): stream.Readable ### shouldPreload -一个函数，用来控制什么文件应该生成 `` 资源预加载提示(resource hints)。 +一个函数，用来控制什么文件应该生成 `` 资源预加载提示 (resource hints)。 默认情况下，只有 JavaScript 和 CSS 文件会被预加载，因为它们是启动应用时所必需的。 @@ -170,7 +170,7 @@ const renderer = createBundleRenderer(bundle, { 出于向后兼容的考虑，此选项默认为 `true`，但建议你尽可能使用 `runInNewContext: false` 或 `runInNewContext: 'once'`。 -> 在 2.3.0 中，此选项有一个 bug，其中 `runInNewContext: false` 仍然使用独立的全局上下文(separate global context)执行 bundle。以下信息假定版本为 2.3.1+。 +> 在 2.3.0 中，此选项有一个 bug，其中 `runInNewContext: false` 仍然使用独立的全局上下文 (separate global context) 执行 bundle。以下信息假定版本为 2.3.1+。 使用 `runInNewContext: false`，bundle 代码将与服务器进程在同一个 `global` 上下文中运行，所以请留意在应用程序代码中尽量避免修改 `global`。 diff --git a/docs/zh/guide/README.md b/docs/zh/guide/README.md index cb8178d7..f31fe2b5 100644 --- a/docs/zh/guide/README.md +++ b/docs/zh/guide/README.md @@ -82,7 +82,7 @@ server.listen(8080) ## 使用一个页面模板 -当你在渲染 Vue 应用程序时，renderer 只从应用程序生成 HTML 标记(markup)。在这个示例中，我们必须用一个额外的 HTML 页面包裹容器，来包裹生成的 HTML 标记。 +当你在渲染 Vue 应用程序时，renderer 只从应用程序生成 HTML 标记 (markup)。在这个示例中，我们必须用一个额外的 HTML 页面包裹容器，来包裹生成的 HTML 标记。 为了简化这些，你可以直接在创建 renderer 时提供一个页面模板。多数时候，我们会将页面模板放在特有的文件中，例如 `index.template.html`： diff --git a/docs/zh/guide/build-config.md b/docs/zh/guide/build-config.md index 70ac04fb..d142642a 100644 --- a/docs/zh/guide/build-config.md +++ b/docs/zh/guide/build-config.md @@ -1,8 +1,8 @@ # 构建配置 -我们假设你已经知道，如何为纯客户端(client-only)项目配置 webpack。服务器端渲染(SSR)项目的配置大体上与纯客户端项目类似，但是我们建议将配置分为三个文件：*base*, *client* 和 *server*。基本配置(base config)包含在两个环境共享的配置，例如，输出路径(output path)，别名(alias)和 loader。服务器配置(server config)和客户端配置(client config)，可以通过使用 [webpack-merge](https://github.com/survivejs/webpack-merge) 来简单地扩展基本配置。 +我们假设你已经知道，如何为纯客户端 (client-only) 项目配置 webpack。服务器端渲染 (SSR) 项目的配置大体上与纯客户端项目类似，但是我们建议将配置分为三个文件：*base*, *client* 和 *server*。基本配置 (base config) 包含在两个环境共享的配置，例如，输出路径 (output path)，别名 (alias) 和 loader。服务器配置 (server config) 和客户端配置 (client config)，可以通过使用 [webpack-merge](https://github.com/survivejs/webpack-merge) 来简单地扩展基本配置。 -## 服务器配置(Server Config) +## 服务器配置 (Server Config) 服务器配置，是用于生成传递给 `createBundleRenderer` 的 server bundle。它应该是这样的： @@ -60,29 +60,29 @@ const renderer = createBundleRenderer('/path/to/vue-ssr-server-bundle.json', { 又或者，你还可以将 bundle 作为对象传递给 `createBundleRenderer`。这对开发过程中的热重载是很有用的 - 具体请查看 HackerNews demo 的[参考设置](https://github.com/vuejs/vue-hackernews-2.0/blob/master/build/setup-dev-server.js)。 -### 扩展说明(Externals Caveats) +### 扩展说明 (Externals Caveats) 请注意，在 `externals` 选项中，我们将 CSS 文件列入白名单。这是因为从依赖模块导入的 CSS 还应该由 webpack 处理。如果你导入依赖于 webpack 的任何其他类型的文件（例如 `*.vue`, `*.sass`），那么你也应该将它们添加到白名单中。 如果你使用 `runInNewContext: 'once'` 或 `runInNewContext: true`，那么你还应该将修改 `global` 的 polyfill 列入白名单，例如 `babel-polyfill`。这是因为当使用新的上下文模式时，**server bundle 中的代码具有自己的 `global` 对象。**由于在使用 Node 7.6+ 时，在服务器并不真正需要它，所以实际上只需在客户端 entry 导入它。 -## 客户端配置(Client Config) +## 客户端配置 (Client Config) -客户端配置(client config)和基本配置(base config)大体上相同。显然你需要把 `entry` 指向你的客户端入口文件。除此之外，如果你使用 `CommonsChunkPlugin`，请确保仅在客户端配置(client config)中使用，因为服务器包需要单独的入口 chunk。 +客户端配置 (client config) 和基本配置 (base config) 大体上相同。显然你需要把 `entry` 指向你的客户端入口文件。除此之外，如果你使用 `CommonsChunkPlugin`，请确保仅在客户端配置 (client config) 中使用，因为服务器包需要单独的入口 chunk。 ### 生成 `clientManifest` > 需要版本 2.3.0+ -除了 server bundle 之外，我们还可以生成客户端构建清单(client build manifest)。使用客户端清单(client manifest)和服务器 bundle(server bundle)，renderer 现在具有了*服务器和客户端*的构建信息，因此它可以自动推断和注入[资源预加载 / 数据预取指令(preload / prefetch directive)](https://css-tricks.com/prefetching-preloading-prebrowsing/)，以及 css 链接 / script 标签到所渲染的 HTML。 +除了 server bundle 之外，我们还可以生成客户端构建清单 (client build manifest)。使用客户端清单 (client manifest) 和服务器 bundle(server bundle)，renderer 现在具有了*服务器和客户端*的构建信息，因此它可以自动推断和注入[资源预加载 / 数据预取指令(preload / prefetch directive)](https://css-tricks.com/prefetching-preloading-prebrowsing/)，以及 css 链接 / script 标签到所渲染的 HTML。 好处是双重的： 1. 在生成的文件名中有哈希时，可以取代 `html-webpack-plugin` 来注入正确的资源 URL。 -2. 在通过 webpack 的按需代码分割特性渲染 bundle 时，我们可以确保对 chunk 进行最优化的资源预加载/数据预取，并且还可以将所需的异步 chunk 智能地注入为 ` ``` -## 服务器端数据预取(Server Data Fetching) +## 服务器端数据预取 (Server Data Fetching) 在 `entry-server.js` 中，我们可以通过路由获得与 `router.getMatchedComponents()` 相匹配的组件，如果组件暴露出 `asyncData`，我们就调用这个方法。然后我们需要将解析完成的状态，附加到渲染上下文(render context)中。 @@ -159,13 +159,13 @@ if (window.__INITIAL_STATE__) { } ``` -## 客户端数据预取(Client Data Fetching) +## 客户端数据预取 (Client Data Fetching) 在客户端，处理数据预取有两种不同方式： 1. **在路由导航之前解析数据：** - 使用此策略，应用程序会等待视图所需数据全部解析之后，再传入数据并处理当前视图。好处在于，可以直接在数据准备就绪时，传入视图渲染完整内容，但是如果数据预取需要很长时间，用户在当前视图会感受到"明显卡顿"。因此，如果使用此策略，建议提供一个数据加载指示器(data loading indicator)。 + 使用此策略，应用程序会等待视图所需数据全部解析之后，再传入数据并处理当前视图。好处在于，可以直接在数据准备就绪时，传入视图渲染完整内容，但是如果数据预取需要很长时间，用户在当前视图会感受到"明显卡顿"。因此，如果使用此策略，建议提供一个数据加载指示器 (data loading indicator)。 我们可以通过检查匹配的组件，并在全局路由钩子函数中执行 `asyncData` 函数，来在客户端实现此策略。注意，在初始路由准备就绪之后，我们应该注册此钩子，这样我们就不必再次获取服务器提取的数据。 @@ -194,7 +194,7 @@ if (window.__INITIAL_STATE__) { return next() } - // 这里如果有加载指示器(loading indicator)，就触发 + // 这里如果有加载指示器 (loading indicator)，就触发 Promise.all(activated.map(c => { if (c.asyncData) { @@ -216,7 +216,7 @@ if (window.__INITIAL_STATE__) { 此策略将客户端数据预取逻辑，放在视图组件的 `beforeMount` 函数中。当路由导航被触发时，可以立即切换视图，因此应用程序具有更快的响应速度。然而，传入视图在渲染时不会有完整的可用数据。因此，对于使用此策略的每个视图组件，都需要具有条件加载状态。 - 这可以通过纯客户端(client-only)的全局 mixin 来实现： + 这可以通过纯客户端 (client-only) 的全局 mixin 来实现： ``` js Vue.mixin({ @@ -235,7 +235,7 @@ if (window.__INITIAL_STATE__) { }) ``` -这两种策略是根本上不同的用户体验决策，应该根据你创建的应用程序的实际使用场景进行挑选。但是无论你选择哪种策略，当路由组件重用（同一路由，但是 params 或 query 已更改，例如，从 `user/1` 到 `user/2`）时，也应该调用 `asyncData` 函数。我们也可以通过纯客户端(client-only)的全局 mixin 来处理这个问题： +这两种策略是根本上不同的用户体验决策，应该根据你创建的应用程序的实际使用场景进行挑选。但是无论你选择哪种策略，当路由组件重用（同一路由，但是 params 或 query 已更改，例如，从 `user/1` 到 `user/2`）时，也应该调用 `asyncData` 函数。我们也可以通过纯客户端 (client-only) 的全局 mixin 来处理这个问题： ``` js Vue.mixin({ @@ -253,7 +253,7 @@ Vue.mixin({ }) ``` -## Store 代码拆分(Store Code Splitting) +## Store 代码拆分 (Store Code Splitting) 在大型应用程序中，我们的 Vuex store 可能会分为多个模块。当然，也可以将这些模块代码，分割到相应的路由组件 chunk 中。假设我们有以下 store 模块： diff --git a/docs/zh/guide/head.md b/docs/zh/guide/head.md index 51814e8b..21d45e15 100644 --- a/docs/zh/guide/head.md +++ b/docs/zh/guide/head.md @@ -1,6 +1,6 @@ # Head 管理 -类似于资源注入，Head 管理遵循相同的理念：我们可以在组件的生命周期中，将数据动态地追加到渲染`上下文`(render `context`)，然后在`模板`中的占位符替换为这些数据。 +类似于资源注入，Head 管理遵循相同的理念：我们可以在组件的生命周期中，将数据动态地追加到渲染`上下文` (render `context`)，然后在`模板`中的占位符替换为这些数据。 > 在 2.3.2+ 的版本，你可以通过 `this.$ssrContext` 来直接访问组件中的服务器端渲染上下文(SSR context)。在旧版本中，你必须通过将其传递给 `createApp()` 并将其暴露于根实例的 `$options` 上，才能手动注入服务器端渲染上下文(SSR context) - 然后子组件可以通过 `this.$root.$options.ssrContext` 来访问它。 @@ -44,7 +44,7 @@ export default process.env.VUE_ENV === 'server' : clientTitleMixin ``` -现在，路由组件可以利用以上 mixin，来控制文档标题(document title)： +现在，路由组件可以利用以上 mixin，来控制文档标题 (document title)： ``` js // Item.vue @@ -87,4 +87,4 @@ export default { --- -使用相同的策略，你可以轻松地将此 mixin 扩展为通用的头部管理工具(generic head management utility)。 +使用相同的策略，你可以轻松地将此 mixin 扩展为通用的头部管理工具 (generic head management utility)。 diff --git a/docs/zh/guide/hydration.md b/docs/zh/guide/hydration.md index 9f27441f..4a49b5f7 100644 --- a/docs/zh/guide/hydration.md +++ b/docs/zh/guide/hydration.md @@ -1,4 +1,4 @@ -# 客户端激活(client-side hydration) +# 客户端激活 (client-side hydration) 所谓客户端激活，指的是 Vue 在浏览器端接管由服务端发送的静态 HTML，使其变为由 Vue 管理的动态 DOM 的过程。 @@ -26,7 +26,7 @@ app.$mount('#app') app.$mount('#app', true) ``` -在开发模式下，Vue 将推断客户端生成的虚拟 DOM 树(virtual DOM tree)，是否与从服务器渲染的 DOM 结构(DOM structure)匹配。如果无法匹配，它将退出混合模式，丢弃现有的 DOM 并从头开始渲染。**在生产模式下，此检测会被跳过，以避免性能损耗。** +在开发模式下，Vue 将推断客户端生成的虚拟 DOM 树 (virtual DOM tree)，是否与从服务器渲染的 DOM 结构 (DOM structure) 匹配。如果无法匹配，它将退出混合模式，丢弃现有的 DOM 并从头开始渲染。**在生产模式下，此检测会被跳过，以避免性能损耗。** ### 一些需要注意的坑 @@ -38,4 +38,4 @@ app.$mount('#app', true) ``` -浏览器会在 `` 内部自动注入 ``，然而，由于 Vue 生成的虚拟 DOM(virtual DOM) 不包含 ``，所以会导致无法匹配。为能够正确匹配，请确保在模板中写入有效的 HTML。 +浏览器会在 `
` 内部自动注入 ``，然而，由于 Vue 生成的虚拟 DOM (virtual DOM) 不包含 ``，所以会导致无法匹配。为能够正确匹配，请确保在模板中写入有效的 HTML。 diff --git a/docs/zh/guide/routing.md b/docs/zh/guide/routing.md index f03e493c..eeaf926b 100644 --- a/docs/zh/guide/routing.md +++ b/docs/zh/guide/routing.md @@ -46,7 +46,7 @@ export function createApp () { } ``` -现在我们需要在 `entry-server.js` 中实现服务器端路由逻辑(server-side routing logic)： +现在我们需要在 `entry-server.js` 中实现服务器端路由逻辑 (server-side routing logic)： ``` js // entry-server.js @@ -118,7 +118,7 @@ const Foo = () => import('./Foo.vue') 在 Vue 2.5 以下的版本中，服务端渲染时异步组件只能用在路由组件上。然而在 2.5+ 的版本中，得益于核心算法的升级，异步组件现在可以在应用中的任何地方使用。 -需要注意的是，你仍然需要在挂载 app 之前调用 `router.onReady`，因为路由器必须要提前解析路由配置中的异步组件，才能正确地调用组件中可能存在的路由钩子。这一步我们已经在我们的服务器入口(server entry)中实现过了，现在我们只需要更新客户端入口(client entry)： +需要注意的是，你仍然需要在挂载 app 之前调用 `router.onReady`，因为路由器必须要提前解析路由配置中的异步组件，才能正确地调用组件中可能存在的路由钩子。这一步我们已经在我们的服务器入口 (server entry) 中实现过了，现在我们只需要更新客户端入口 (client entry)： ``` js // entry-client.js diff --git a/docs/zh/guide/streaming.md b/docs/zh/guide/streaming.md index 0d07c3d8..3994fdf1 100644 --- a/docs/zh/guide/streaming.md +++ b/docs/zh/guide/streaming.md @@ -1,4 +1,4 @@ -# 流式渲染(streaming) +# 流式渲染 (Streaming) 对于 `vue-server-renderer` 的基本 renderer 和 bundle renderer 都提供开箱即用的流式渲染功能。所有你需要做的就是，用 `renderToStream` 替代 `renderToString`： @@ -24,10 +24,10 @@ stream.on('error', err => { }) ``` -## 流式传输说明(Streaming Caveats) +## 流式传输说明 (Streaming Caveats) -在流式渲染模式下，当 renderer 遍历虚拟 DOM 树(virtual DOM tree)时，会尽快发送数据。这意味着我们可以尽快获得"第一个 chunk"，并开始更快地将其发送给客户端。 +在流式渲染模式下，当 renderer 遍历虚拟 DOM 树 (virtual DOM tree) 时，会尽快发送数据。这意味着我们可以尽快获得"第一个 chunk"，并开始更快地将其发送给客户端。 -然而，当第一个数据 chunk 被发出时，子组件甚至可能不被实例化，它们的生命周期钩子也不会被调用。这意味着，如果子组件需要在其生命周期钩子函数中，将数据附加到渲染上下文(render context)，当流(stream)启动时，这些数据将不可用。这是因为，大量上下文信息(context information)（如头信息(head information)或内联关键 CSS(inline critical CSS)）需要在应用程序标记(markup)之前出现，我们基本上必须等待流(stream)完成后，才能开始使用这些上下文数据。 +然而，当第一个数据 chunk 被发出时，子组件甚至可能不被实例化，它们的生命周期钩子也不会被调用。这意味着，如果子组件需要在其生命周期钩子函数中，将数据附加到渲染上下文 (render context)，当流 (stream) 启动时，这些数据将不可用。这是因为，大量上下文信息 (context information)（如头信息 (head information) 或内联关键 CSS(inline critical CSS)）需要在应用程序标记 (markup) 之前出现，我们基本上必须等待流(stream)完成后，才能开始使用这些上下文数据。 因此，如果你依赖由组件生命周期钩子函数填充的上下文数据，则**不建议**使用流式传输模式。 diff --git a/docs/zh/guide/structure.md b/docs/zh/guide/structure.md index c1512abc..d66002bc 100644 --- a/docs/zh/guide/structure.md +++ b/docs/zh/guide/structure.md @@ -2,9 +2,9 @@ ## 避免状态单例 -当编写纯客户端(client-only)代码时，我们习惯于每次在新的上下文中对代码进行取值。但是，Node.js 服务器是一个长期运行的进程。当我们的代码进入该进程时，它将进行一次取值并留存在内存中。这意味着如果创建一个单例对象，它将在每个传入的请求之间共享。 +当编写纯客户端 (client-only) 代码时，我们习惯于每次在新的上下文中对代码进行取值。但是，Node.js 服务器是一个长期运行的进程。当我们的代码进入该进程时，它将进行一次取值并留存在内存中。这意味着如果创建一个单例对象，它将在每个传入的请求之间共享。 -如基本示例所示，我们**为每个请求创建一个新的根 Vue 实例**。这与每个用户在自己的浏览器中使用新应用程序的实例类似。如果我们在多个请求之间使用一个共享的实例，很容易导致交叉请求状态污染(cross-request state pollution)。 +如基本示例所示，我们**为每个请求创建一个新的根 Vue 实例**。这与每个用户在自己的浏览器中使用新应用程序的实例类似。如果我们在多个请求之间使用一个共享的实例，很容易导致交叉请求状态污染 (cross-request state pollution)。 因此，我们不应该直接创建一个应用程序实例，而是应该暴露一个可以重复执行的工厂函数，为每个请求创建新的应用程序实例： @@ -111,7 +111,7 @@ app.$mount('#app') ### `entry-server.js`: -服务器 entry 使用 default export 导出函数，并在每次渲染中重复调用此函数。此时，除了创建和返回应用程序实例之外，它不会做太多事情 - 但是稍后我们将在此执行服务器端路由匹配(server-side route matching)和数据预取逻辑(data pre-fetching logic)。 +服务器 entry 使用 default export 导出函数，并在每次渲染中重复调用此函数。此时，除了创建和返回应用程序实例之外，它不会做太多事情 - 但是稍后我们将在此执行服务器端路由匹配 (server-side route matching) 和数据预取逻辑 (data pre-fetching logic)。 ``` js import { createApp } from './app' diff --git a/docs/zh/guide/universal.md b/docs/zh/guide/universal.md index 680fabd4..1233c485 100644 --- a/docs/zh/guide/universal.md +++ b/docs/zh/guide/universal.md @@ -4,15 +4,15 @@ ## 服务器上的数据响应 -在纯客户端应用程序(client-only app)中，每个用户会在他们各自的浏览器中使用新的应用程序实例。对于服务器端渲染，我们也希望如此：每个请求应该都是全新的、独立的应用程序实例，以便不会有交叉请求造成的状态污染(cross-request state pollution)。 +在纯客户端应用程序 (client-only app) 中，每个用户会在他们各自的浏览器中使用新的应用程序实例。对于服务器端渲染，我们也希望如此：每个请求应该都是全新的、独立的应用程序实例，以便不会有交叉请求造成的状态污染 (cross-request state pollution)。 -因为实际的渲染过程需要确定性，所以我们也将在服务器上“预取”数据("pre-fetching" data) - 这意味着在我们开始渲染时，我们的应用程序就已经解析完成其状态。也就是说，将数据进行响应式的过程在服务器上是多余的，所以默认情况下禁用。禁用响应式数据，还可以避免将「数据」转换为「响应式对象」的性能开销。 +因为实际的渲染过程需要确定性，所以我们也将在服务器上“预取”数据 ("pre-fetching" data) - 这意味着在我们开始渲染时，我们的应用程序就已经解析完成其状态。也就是说，将数据进行响应式的过程在服务器上是多余的，所以默认情况下禁用。禁用响应式数据，还可以避免将「数据」转换为「响应式对象」的性能开销。 ## 组件生命周期钩子函数 -由于没有动态更新，所有的生命周期钩子函数中，只有 `beforeCreate` 和 `created` 会在服务器端渲染(SSR)过程中被调用。这就是说任何其他生命周期钩子函数中的代码（例如 `beforeMount` 或 `mounted`），只会在客户端执行。 +由于没有动态更新，所有的生命周期钩子函数中，只有 `beforeCreate` 和 `created` 会在服务器端渲染 (SSR) 过程中被调用。这就是说任何其他生命周期钩子函数中的代码（例如 `beforeMount` 或 `mounted`），只会在客户端执行。 -此外还需要注意的是，你应该避免在 `beforeCreate` 和 `created` 生命周期时产生全局副作用的代码，例如在其中使用 `setInterval` 设置 timer。在纯客户端(client-side only)的代码中，我们可以设置一个 timer，然后在 `beforeDestroy` 或 `destroyed` 生命周期时将其销毁。但是，由于在 SSR 期间并不会调用销毁钩子函数，所以 timer 将永远保留下来。为了避免这种情况，请将副作用代码移动到 `beforeMount` 或 `mounted` 生命周期中。 +此外还需要注意的是，你应该避免在 `beforeCreate` 和 `created` 生命周期时产生全局副作用的代码，例如在其中使用 `setInterval` 设置 timer。在纯客户端 (client-side only) 的代码中，我们可以设置一个 timer，然后在 `beforeDestroy` 或 `destroyed` 生命周期时将其销毁。但是，由于在 SSR 期间并不会调用销毁钩子函数，所以 timer 将永远保留下来。为了避免这种情况，请将副作用代码移动到 `beforeMount` 或 `mounted` 生命周期中。 ## 访问特定平台(Platform-Specific) API @@ -20,13 +20,13 @@ 对于共享于服务器和客户端，但用于不同平台 API 的任务(task)，建议将平台特定实现包含在通用 API 中，或者使用为你执行此操作的 library。例如，[axios](https://github.com/axios/axios) 是一个 HTTP 客户端，可以向服务器和客户端都暴露相同的 API。 -对于仅浏览器可用的 API，通常方式是，在「纯客户端(client-only)」的生命周期钩子函数中惰性访问(lazily access)它们。 +对于仅浏览器可用的 API，通常方式是，在「纯客户端 (client-only)」的生命周期钩子函数中惰性访问 (lazily access) 它们。 -请注意，考虑到如果第三方 library 不是以上面的通用用法编写，则将其集成到服务器渲染的应用程序中，可能会很棘手。你*可能*要通过模拟(mock)一些全局变量来使其正常运行，但这只是 hack 的做法，并且可能会干扰到其他 library 的环境检测代码。 +请注意，考虑到如果第三方 library 不是以上面的通用用法编写，则将其集成到服务器渲染的应用程序中，可能会很棘手。你*可能*要通过模拟 (mock) 一些全局变量来使其正常运行，但这只是 hack 的做法，并且可能会干扰到其他 library 的环境检测代码。 ## 自定义指令 -大多数自定义指令直接操作 DOM，因此会在服务器端渲染(SSR)过程中导致错误。有两种方法可以解决这个问题： +大多数自定义指令直接操作 DOM，因此会在服务器端渲染 (SSR) 过程中导致错误。有两种方法可以解决这个问题： 1. 推荐使用组件作为抽象机制，并运行在「虚拟 DOM 层级(Virtual-DOM level)」（例如，使用渲染函数(render function)）。