Skip to content
This repository was archived by the owner on Aug 8, 2022. It is now read-only.

Translated build (noun) into 构建版本 #645

Merged
merged 1 commit into from
Aug 14, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/api/application-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ app.mixin({
配置运行时编译器的选项。设置在这个对象上的值将会被传入浏览器内的模板编译器,并影响配置过的应用内的每个组件。注意,你也可以使用 [`compilerOptions` 选项](/api/options-misc.html#compileroptions)在每个组件的基础上覆写这些选项。

::: tip 重要
该配置选项只在完整的构建中生效 (例如可以在浏览器中编译模板的独立版 `vue.js`)。如果你使用的是附带额外构建设置的仅运行时版,编译器选项必须传入 `@vue/compiler-dom` 构建工具的配置来替代
该配置选项只在完整的构建版本中生效 (例如可以在浏览器中编译模板的独立版 `vue.js`)。如果你使用的是附带额外构建设置的仅运行时版本,编译器选项必须传入 `@vue/compiler-dom` 构建工具的配置来替代

- 对 `vue-loader` 来说:[通过 `compilerOptions` loader 选项传入](https://vue-loader.vuejs.org/options.html#compileroptions)。也可以查阅 [`vue-cli` 中的配置方式](https://cli.vuejs.org/zh/guide/webpack.html#修改-loader-选项)。

Expand Down
4 changes: 2 additions & 2 deletions src/api/built-in-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@
`<keep-alive>`、`<transition>`、`<transition-group>` 和 `<teleport>` 组件都可以被打包工具 tree-shake。所以它们只会在被使用的时候被引入。如果你需要直接访问它们,也可以将它们显性导入。

```js
// Vue 的 CDN 构建
// Vue 的 CDN 构建版本
const { KeepAlive, Teleport, Transition, TransitionGroup } = Vue
```

```js
// Vue 的 ESM 构建
// Vue 的 ESM 构建版本
import { KeepAlive, Teleport, Transition, TransitionGroup } from 'vue'
```

Expand Down
2 changes: 1 addition & 1 deletion src/api/global-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebarDepth: 1

# 全局 API

如果你使用的是 CDN 构建,那么全局 API 可以通过全局对象 `Vue` 来访问,例如:
如果你使用的是 CDN 构建版本,那么全局 API 可以通过全局对象 `Vue` 来访问,例如:

```js
const { createApp, h, nextTick } = Vue
Expand Down
2 changes: 1 addition & 1 deletion src/api/options-misc.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@
```

::: tip 重要
和应用级别的 `compilerOptions` 配置类似,该选项只会在使用完整的构建在浏览器内编译模板时生效
和应用级别的 `compilerOptions` 配置类似,该选项只会在使用完整的构建版本在浏览器内编译模板时生效
:::

## delimiters <Badge text="deprecated" type="warning" />
Expand Down
10 changes: 5 additions & 5 deletions src/guide/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ $ npm install -D @vue/compiler-sfc

除了 `@vue/compiler-sfc` 之外,你还需要为已选择的打包工具选择一个配套的单文件组件 loader 或 plugin。更多信息请查阅[单文件组件文档](../guide/single-file-component.html)。

大多数情况下,我们更倾向于使用 Vue CLI 来创建一个配置最小化的 webpack 构建
大多数情况下,我们更倾向于使用 Vue CLI 来创建一个配置最小化的 webpack 构建版本

## 命令行工具 (CLI)

Expand Down Expand Up @@ -124,10 +124,10 @@ $ yarn dev

- 若要通过浏览器中的 `<script src="...">` 直接使用,则暴露 Vue 全局。
- 浏览器内模板编译:
- `vue.global.js` 是包含编译器和运行时的“完整”构建,因此它支持动态编译模板。
- `vue.global.js` 是包含编译器和运行时的“完整”构建版本,因此它支持动态编译模板。
- `vue.runtime.global.js` 只包含运行时,并且需要在构建步骤期间预编译模板。
- 内联所有 Vue 核心内部包——即:它是一个单独的文件,不依赖于其他文件。这意味着你必须导入此文件和此文件中的所有内容,以确保获得相同的代码实例。
- 包含硬编码的 prod/dev 分支,并且 prod 构建是预先压缩过的。将 `*.prod.js` 文件用于生产环境。
- 包含硬编码的 prod/dev 分支,并且 prod 构建版本是预先压缩过的。将 `*.prod.js` 文件用于生产环境。

:::tip 提示
全局打包不是 [UMD](https://github.com/umdjs/umd) 构建的,它们被打包成 [IIFEs](https://developer.mozilla.org/en-US/docs/Glossary/IIFE),并且仅用于通过 `<script src="...">` 直接使用。
Expand All @@ -136,7 +136,7 @@ $ yarn dev
#### `vue(.runtime).esm-browser(.prod).js`:

- 用于通过原生 ES 模块导入使用 (在浏览器中通过 `<script type="module">` 来使用)。
- 与全局构建共享相同的运行时编译、依赖内联和硬编码的 prod/dev 行为。
- 与全局构建版本共享相同的运行时编译、依赖内联和硬编码的 prod/dev 行为。

### 使用构建工具

Expand All @@ -146,7 +146,7 @@ $ yarn dev
- 留下 prod/dev 分支的 `process.env.NODE_ENV` 守卫语句 (必须由构建工具替换)。
- 不提供压缩版本 (打包后与其余代码一起压缩)。
- import 依赖 (例如:`@vue/runtime-core`,`@vue/runtime-compiler`)
- 导入的依赖项也是 esm bundler 构建,并将依次导入其依赖项 (例如:@vue/runtime-core imports @vue/reactivity)。
- 导入的依赖项也是 esm bundler 构建版本,并将依次导入其依赖项 (例如:@vue/runtime-core imports @vue/reactivity)。
- 这意味着你**可以**单独安装/导入这些依赖,而不会导致这些依赖项的不同实例,但你必须确保它们都为同一版本。
- 浏览器内模板编译:
- `vue.runtime.esm-bundler.js` **(默认)** 仅运行时,并要求所有模板都要预先编译。这是构建工具的默认入口 (通过 `package.json` 中的 module 字段),因为在使用构建工具时,模板通常是预先编译的 (例如:在 `*.vue` 文件中)。
Expand Down
6 changes: 3 additions & 3 deletions src/guide/migration/global-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ import { createApp } from 'vue'
const app = createApp({})
```

如果你使用的是 Vue 的 [CDN](/guide/installation.html#cdn) 构建,那么 `createApp` 是通过全局的 `Vue` 对象暴露的。
如果你使用的是 Vue 的 [CDN](/guide/installation.html#cdn) 构建版本,那么 `createApp` 是通过全局的 `Vue` 对象暴露的。

```js
const { createApp } = Vue
Expand All @@ -91,9 +91,9 @@ const app = createApp({})

### `config.productionTip` 移除

在 Vue 3.x 中,“使用生产版本”提示仅在使用“dev + full build”(包含运行时编译器并有警告的构建) 时才会显示。
在 Vue 3.x 中,“使用生产版本”提示仅在使用“dev + full build”(包含运行时编译器并有警告的构建版本) 时才会显示。

对于 ES 模块构建,由于它们是与 bundler 一起使用的,而且在大多数情况下,CLI 或样板已经正确地配置了生产环境,所以本技巧将不再出现。
对于 ES 模块构建版本,由于它们是与 bundler 一起使用的,而且在大多数情况下,CLI 或样板已经正确地配置了生产环境,所以本技巧将不再出现。

[迁移构建标记:`CONFIG_PRODUCTION_TIP`](migration-build.html#兼容性配置)

Expand Down
6 changes: 3 additions & 3 deletions src/guide/migration/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
本指南主要是为有 Vue 2 经验的用户希望了解 Vue 3 的新功能和更改而提供的。**在试用 Vue 3 之前,你不必从头阅读这些内容**。虽然看起来有很多变化,但很多你已经了解和喜欢 Vue 的部分仍是一样的。不过我们希望尽可能全面,并为每处变化提供详细的例子。

- [快速开始](#快速开始)
- [迁移构建](#迁移构建)
- [迁移构建版本](#迁移构建版本)
- [值得注意的新特性](#值得注意的新特性)
- [非兼容的变更](#非兼容的变更)
- [支持的库](#官方支持的库)
Expand Down Expand Up @@ -40,9 +40,9 @@
# 选择 vue 3 preset
```

## 迁移构建
## 迁移构建版本

如果你有基于 Vue 2 的项目或者库,它要升级到 Vue 3,我们提供了与 Vue 2 兼容 API 的 Vue 3 构建,查看[迁移构建](./migration-build.html)获取完整的细节。
如果你有基于 Vue 2 的项目或者库,它要升级到 Vue 3,我们提供了与 Vue 2 兼容 API 的 Vue 3 构建版本,查看[迁移构建版本](./migration-build.html)获取完整的细节。

## 值得注意的新特性

Expand Down
28 changes: 14 additions & 14 deletions src/guide/migration/migration-build.md
Original file line number Diff line number Diff line change
@@ -1,36 +1,36 @@
# 迁移构建
# 迁移构建版本

## 概述

`@vue/compat` (即“迁移构建”) 是一个 Vue 3 的构建,提供了可配置的兼容 Vue 2 的行为。
`@vue/compat` (即“迁移构建版本”) 是一个 Vue 3 的构建版本,提供了可配置的兼容 Vue 2 的行为。

该构建默认运行在 Vue 2 的模式下——大部分公有 API 的行为和 Vue 2 一致,仅有一小部分例外。使用在 Vue 3 中发生改变或被废弃的特性时会抛出运行时警告。一个特性的兼容性也可以基于单个组件进行开启或禁用。
该构建版本默认运行在 Vue 2 的模式下——大部分公有 API 的行为和 Vue 2 一致,仅有一小部分例外。使用在 Vue 3 中发生改变或被废弃的特性时会抛出运行时警告。一个特性的兼容性也可以基于单个组件进行开启或禁用。

### 预期用例

- 将一个 Vue 2 应用升级为 Vue 3 (存在[限制](#已知的限制))
- 迁移一个库以支持 Vue 3
- 对于尚未尝试 Vue 3 的资深 Vue 2 开发者来说,迁移构建可以用来代替 Vue 3 以更好地学习版本之间的差异。
- 对于尚未尝试 Vue 3 的资深 Vue 2 开发者来说,迁移构建版本可以用来代替 Vue 3 以更好地学习版本之间的差异。

### 已知的限制

虽然我们已经努力使迁移构建尽可能地模拟 Vue 2 的行为,但仍有一些限制可能会阻止应用的顺利升级:
虽然我们已经努力使迁移构建版本尽可能地模拟 Vue 2 的行为,但仍有一些限制可能会阻止应用的顺利升级:

- 基于 Vue 2 内部 API 或文档中未记载行为的依赖。最常见的情况就是使用 `VNodes` 上的私有 property。如果你的项目依赖诸如 [Vuetify](https://vuetifyjs.com/zh-Hans/)、[Quasar](https://quasar.dev/) 或 [Element UI](https://element.eleme.io/#/zh-CN) 等组件库,那么最好等待一下它们的 Vue 3 兼容版本。

- 对 IE11 的支持:[Vue 3 已经官方放弃对 IE11 的支持](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0038-vue3-ie11-support.md)。如果仍然需要支持 IE11 或更低版本,那你仍需继续使用 Vue 2。

- 服务端渲染:该迁移构建可以被用于服务端渲染,但是迁移一个自定义的服务端渲染设置有更多工作要做。大致的思路是将 `vue-server-renderer` 替换为 [`@vue/server-renderer`](https://github.com/vuejs/vue-next/tree/master/packages/server-renderer)。Vue 3 不再提供一个包渲染器,且我们推荐使用 [Vite](https://cn.vitejs.dev/guide/ssr.html) 以支持 Vue 3 服务端渲染。如果你正在使用 [Nuxt.js](https://zh.nuxtjs.org/),那最好等待一下 Nuxt 3。
- 服务端渲染:该迁移构建版本可以被用于服务端渲染,但是迁移一个自定义的服务端渲染设置有更多工作要做。大致的思路是将 `vue-server-renderer` 替换为 [`@vue/server-renderer`](https://github.com/vuejs/vue-next/tree/master/packages/server-renderer)。Vue 3 不再提供一个包渲染器,且我们推荐使用 [Vite](https://cn.vitejs.dev/guide/ssr.html) 以支持 Vue 3 服务端渲染。如果你正在使用 [Nuxt.js](https://zh.nuxtjs.org/),那最好等待一下 Nuxt 3。

### 预期

请注意迁移构建旨在覆盖在文档中公开记载的 Vue 2 API 和行为。如果应用依赖了未记载的行为导致在迁移构建下运行失败,我们可能不太会调整迁移构建以迎合这种特殊情况。请考虑重构或移除导致这些问题行为的依赖。
请注意迁移构建版本旨在覆盖在文档中公开记载的 Vue 2 API 和行为。如果应用依赖了未记载的行为导致在迁移构建下运行失败,我们可能不太会调整迁移构建版本以迎合这种特殊情况。请考虑重构或移除导致这些问题行为的依赖。

多留意一下:如果你的应用较大且复杂,即便有了构建迁移,整个迁移过程也会是一个挑战。如果你的应用不幸无法顺利升级,请留意我们正在计划将组合式 API 等其它 Vue 3 特性迁移回 Vue 2.7 (预计在 2021 年第三季度末)。
多留意一下:如果你的应用较大且复杂,即便有了迁移构建版本,整个迁移过程也会是一个挑战。如果你的应用不幸无法顺利升级,请留意我们正在计划将组合式 API 等其它 Vue 3 特性迁移回 Vue 2.7 (预计在 2021 年第三季度末)。

如果应用在迁移构建中顺利运行,你**可以**在迁移完成之前将其发布到生产环境。尽管存在一些小的性能或包大小的问题,但应该不会显著地影响到生产环境的用户体验。当你有基于 Vue 2 行为的依赖且无法升级/替换时,可能不得不这样做。
如果应用在迁移构建版本中顺利运行,你**可以**在迁移完成之前将其发布到生产环境。尽管存在一些小的性能或包大小的问题,但应该不会显著地影响到生产环境的用户体验。当你有基于 Vue 2 行为的依赖且无法升级/替换时,可能不得不这样做。

该迁移构建会从 3.1 开始提供,且会随着 3.2 的发布计划进行持续发布。我们计划在将来某个小版本号起最终停止发布迁移构建 (在 2021 年底前至少不会),因此你仍需要在此之前将其迁移到标准构建
该迁移构建版本会从 3.1 开始提供,且会随着 3.2 的发布计划进行持续发布。我们计划在将来某个小版本号起最终停止发布迁移构建版本 (在 2021 年底前至少不会),因此你仍需要在此之前将其迁移到标准构建版本

## 升级流程

Expand Down Expand Up @@ -193,7 +193,7 @@

[示例提交](https://github.com/vuejs/vue-hackernews-2.0/commit/d0c7d3ae789be71b8fd56ce79cb4cb1f921f893b)

11. 当修复了所有警告以后,你就可以移除迁移构建并切换为 Vue 3。注意如果存在基于 Vue 2 行为的依赖,你可能无法做到这一点。
11. 当修复了所有警告以后,你就可以移除迁移构建版本并切换为 Vue 3。注意如果存在基于 Vue 2 行为的依赖,你可能无法做到这一点。

[示例提交](https://github.com/vuejs/vue-hackernews-2.0/commit/9beb45490bc5f938c9e87b4ac1357cfb799565bd)

Expand Down Expand Up @@ -242,7 +242,7 @@ export default {

### 针对编译器的配置

以 `COMPILER_` 开头的特性是针对编译器的:如果你正在使用完整构建 (含浏览器内编译器),它们可以在运行时中被配置。然而如果使用构建设置,它们必须换为通过在构建配置中的 `compilerOptions` 进行配置 (参阅上述的配置)。
以 `COMPILER_` 开头的特性是针对编译器的:如果你正在使用完整构建版本 (含浏览器内编译器),它们可以在运行时中被配置。然而如果使用构建设置,它们必须换为通过在构建配置中的 `compilerOptions` 进行配置 (参阅上述的配置)。

## 特性参考

Expand Down Expand Up @@ -270,8 +270,8 @@ export default {

| ID | 类型 | 描述 | 文档 |
| ---- | ---- | ---- | ---- |
| CONFIG_IGNORED_ELEMENTS | ◐ | `config.ignoredElements` 现在改为了 `config.compilerOptions.isCustomElement` (只在浏览器编译器构建中)。如果使用了构建设置,`isCustomElement` 必须通过构建配置传入。 | [链接](/guide/migration/global-api.html#config-ignoredelements-替换为-config-iscustomelement) |
| COMPILER_INLINE_TEMPLATE | ◐ | `inline-template` 被移除 (兼容模式只在浏览器编译器构建中支持) | [链接](/guide/migration/inline-template-attribute.html) |
| CONFIG_IGNORED_ELEMENTS | ◐ | `config.ignoredElements` 现在改为了 `config.compilerOptions.isCustomElement` (只在浏览器编译器构建版本中)。如果使用了构建设置,`isCustomElement` 必须通过构建配置传入。 | [链接](/guide/migration/global-api.html#config-ignoredelements-替换为-config-iscustomelement) |
| COMPILER_INLINE_TEMPLATE | ◐ | `inline-template` 被移除 (兼容模式只在浏览器编译器构建版本中支持) | [链接](/guide/migration/inline-template-attribute.html) |
| PROPS_DEFAULT_THIS | ◐ | prop 的默认工厂方法不再可以访问 `this` (在兼容模式下,`this` 不是一个真实的实例——它只暴露 prop、`$options` 和注入) | [链接](/guide/migration/props-default-this.html) |
| INSTANCE_DESTROY | ◐ | `$destroy` 实例方法被移除 (在兼容模式下,只在根实例下支持) | |
| GLOBAL_PRIVATE_UTIL | ◐ | `Vue.util` 是私有的,且不再可用 | |
Expand Down
2 changes: 1 addition & 1 deletion src/guide/migration/render-function-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@ export default {

- Vue 不应绑定到库中
- 对于模块构建,导入应该保持独立,由最终用户的打包器处理
- 对于 UMD / browser 构建,应该首先尝试全局 Vue.h,不存在时再使用 require 调用
- 对于 UMD / browser 构建版本,应该首先尝试全局 Vue.h,不存在时再使用 require 调用

## 下一步

Expand Down
10 changes: 5 additions & 5 deletions src/guide/ssr/build-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

一个服务端渲染项目的 webpack 配置和一个只有客户端的项目类似。如果你不熟悉 webpack 配置,你可以在 [Vue CLI](https://cli.vuejs.org/zh/guide/webpack.html#webpack-相关) 或[手动配置 Vue Loader](https://vue-loader.vuejs.org/zh/guide/#手动设置) 的文档中找到更多信息。

## 和客户端构建的关键不同
## 和客户端构建版本的关键不同

1. 我们需要为服务端代码创建一个 [webpack manifest](https://webpack.js.org/concepts/manifest/)。这是一个让 webpack 追踪所有的模块如何对应到生成的包中的 JSON 文件。

2. 我们应该[将应用依赖变为外部扩展](https://webpack.js.org/configuration/externals/)。这使得服务端构建更加快速并生成更小的包文件。做这件事的时候,我们需要把交给 webpack 处理的依赖 (如 `.css` 或 `.vue` 文件) 排除在外。
2. 我们应该[将应用依赖变为外部扩展](https://webpack.js.org/configuration/externals/)。这使得服务端构建版本更加快速并生成更小的包文件。做这件事的时候,我们需要把交给 webpack 处理的依赖 (如 `.css` 或 `.vue` 文件) 排除在外。

3. 我们需要将 webpack 的[目标](https://webpack.js.org/concepts/targets/)改为 Node.js。这会允许 webpack 以适合于 Node 的方式处理动态导入,同时也告诉 `vue-loader` 在编译 Vue 组件的时候抛出面向服务端的代码。

Expand All @@ -22,7 +22,7 @@

## 配置示例

以下是一个 `vue.config.js` 的例子,这个例子向一个 Vue CLI 工程加入了服务端渲染,但这也可以适配于任何 webpack 构建
以下是一个 `vue.config.js` 的例子,这个例子向一个 Vue CLI 工程加入了服务端渲染,但这也可以适配于任何 webpack 构建版本

```js
const { WebpackManifestPlugin } = require('webpack-manifest-plugin')
Expand All @@ -31,7 +31,7 @@ const webpack = require('webpack')

module.exports = {
chainWebpack: webpackConfig => {
// 我们需要禁用 cache loader,否则客户端构建会从服务端构建使用缓存过的组件
// 我们需要禁用 cache loader,否则客户端构建版本会从服务端构建版本使用缓存过的组件
webpackConfig.module.rule('vue').uses.delete('cache-loader')
webpackConfig.module.rule('js').uses.delete('cache-loader')
webpackConfig.module.rule('ts').uses.delete('cache-loader')
Expand Down Expand Up @@ -95,7 +95,7 @@ module.exports = {

## 生成 `clientManifest`

对于服务端的包,我们还额外生成一个客户端构建单 (manifest)。有了这个客户端构建单和服务端的包,渲染器现在就同时有了服务端*和*客户端构建的信息。这样它就可以自动推断并向渲染出来的 HTML 中注入 [preload / prefetch 指令](https://css-tricks.com/prefetching-preloading-prebrowsing/)、`<link>` 和 `<script>` 标签。
对于服务端的包,我们还额外生成一个客户端构建单 (manifest)。有了这个客户端构建单和服务端的包,渲染器现在就同时有了服务端*和*客户端构建版本的信息。这样它就可以自动推断并向渲染出来的 HTML 中注入 [preload / prefetch 指令](https://css-tricks.com/prefetching-preloading-prebrowsing/)、`<link>` 和 `<script>` 标签。

带来的好处是双向的:

Expand Down
Loading