docs(zh): update (#2016) [ci skip]

Author: Jinjiang

docs/.vuepress/config.js

@@ -7,7 +7,7 @@ module.exports = {
     },
     '/zh/': {
       lang: 'zh-CN',
-      title: 'Vue CLI',
+      title: 'Vue CLI 3',
       description: '🛠️ Vue.js 开发的标准工具'
     },
   },
@@ -118,12 +118,12 @@ module.exports = {
             link: '/zh/config/'
           },
           {
-            text: '开发指南',
+            text: '插件开发指南',
             items: [
-              { text: 'Plugin Dev Guide', link: '/zh/dev-guide/plugin-dev.md' },
-              { text: 'UI Plugin Info', link: '/zh/dev-guide/ui-info.md' },
-              { text: 'UI Plugin API', link: '/zh/dev-guide/ui-api.md' },
-              { text: 'UI Localization', link: '/zh/dev-guide/ui-localization.md' }
+              { text: '插件开发指南', link: '/zh/dev-guide/plugin-dev.md' },
+              { text: 'UI 插件信息', link: '/zh/dev-guide/ui-info.md' },
+              { text: 'UI 插件 API', link: '/zh/dev-guide/ui-api.md' },
+              { text: 'UI 本地化', link: '/zh/dev-guide/ui-localization.md' }
             ]
           },
           {
@@ -147,20 +147,21 @@ module.exports = {
         sidebar: {
           '/zh/guide/': [
             '/zh/guide/',
+            '/zh/guide/installation',
             {
-              title: 'CLI',
+              title: '基础',
               collapsable: false,
               children: [
-                '/zh/guide/creating-a-project',
                 '/zh/guide/prototyping',
-                '/zh/guide/plugins-and-presets'
+                '/zh/guide/creating-a-project',
+                '/zh/guide/plugins-and-presets',
+                '/zh/guide/cli-service'
               ]
             },
             {
               title: '开发',
               collapsable: false,
               children: [
-                '/zh/guide/cli-service',
                 '/zh/guide/browser-compatibility',
                 '/zh/guide/html-and-static-assets',
                 '/zh/guide/css',
@@ -173,9 +174,15 @@ module.exports = {
           ],
           '/zh/dev-guide/': [
             '/zh/dev-guide/plugin-dev.md',
-            '/zh/dev-guide/ui-info.md',
-            '/zh/dev-guide/ui-api.md',
-            '/zh/dev-guide/ui-localization.md'
+            {
+              title: 'UI 开发',
+              collapsable: false,
+              children: [
+                '/zh/dev-guide/ui-info.md',
+                '/zh/dev-guide/ui-api.md',
+                '/zh/dev-guide/ui-localization.md'
+              ]
+            }
           ]
         }
       }

docs/zh/README.md

@@ -10,7 +10,7 @@ features:
   details: 它的插件系统可以让社区根据常见需求构建和共享可复用的解决方案。
 - title: 无需 Eject
   details: Vue CLI 完全是可配置的，无需 eject。这样你的项目就可以长期保持更新了。
-- title: 基于 CLI 的图形化界面
+- title: CLI 之上的图形化界面
   details: 通过配套的图形化界面创建、开发和管理你的项目。
 - title: 即刻创建原型
   details: 用单个 Vue 文件即刻实践新的灵感。
@@ -21,10 +21,18 @@ footer: MIT Licensed | Copyright © 2018-present Evan You
 
 ## 起步
 
+安装：
+
 ``` bash
 npm install -g @vue/cli
 # OR
 yarn global add @vue/cli
+```
+
+创建一个项目：
 
+``` bash
 vue create my-project
+# OR
+vue ui
 ```

docs/zh/config/README.md

@@ -8,6 +8,8 @@ sidebar: auto
 
 有些针对 `@vue/cli` 的全局配置，例如你惯用的包管理器和你本地保存的 preset，都保存在 home 目录下一个名叫 `.vuerc` 的 JSON 文件。你可以用编辑器直接编辑这个文件来更改已保存的选项。
 
+你也可以使用 `vue config` 命令来审查或修改全局的 CLI 配置。
+
 ## 目标浏览器
 
 请查阅指南中的[浏览器兼容性](../guide/browser-compatibility.md#browserslist)章节。
@@ -44,7 +46,7 @@ module.exports = {
   }
   ```
 
-  这个值也可以被设置为空字符串 (`''`) 这样所有的资源都会被链接为相对路径，这样打出来的包可以用在类似 Cordova hybrid 应用的文件系统中。需要注意的生成的 CSS 文件要始终放在输出路径的根部，以确保 CSS 中的 URL 正常工作。
+  这个值也可以被设置为空字符串 (`''`) 这样所有的资源都会被链接为相对路径，这样打出来的包可以用在类似 Cordova hybrid 应用的文件系统中。**注意：生成的 CSS 文件要始终放在输出路径的根部，以确保 CSS 中的 URL 正常工作。**
 
   ::: tip 提示
   请始终使用 `baseUrl` 而不要修改 webpack 的 `output.publicPath`。
@@ -66,7 +68,25 @@ module.exports = {
 - Type: `string`
 - Default: `''`
 
-  放置生成的静态资源 (js、css、img、fonts) 的目录。
+  放置生成的静态资源 (js、css、img、fonts) 的 (相对于 `outputDir` 的) 目录。
+
+  ::: tip 提示
+  从生成的资源覆写 filename 或 chunkFilename 时，`assetsDir` 会被忽略。
+  :::
+
+### indexPath
+
+- Type: `string`
+- Default: `'index.html'`
+
+  指定生成的 `index.html` 的输出路径 (相对于 `outputDir`)。也可以是一个绝对路径。
+
+### filenameHashing
+
+- Type: `boolean`
+- Default: `true`
+
+  默认情况下，生成的静态资源在它们的文件名中包含了 hash 以便更好的控制缓存。然而，这也要求 index 的 HTML 是被 Vue CLI 自动生成的。如果你无法使用 Vue CLI 生成的 index HTML，你可以通过将这个选项设为 `false` 来关闭文件名哈希。
 
 ### pages
 
@@ -75,7 +95,7 @@ module.exports = {
 
   在 multi-page 模式下构建应用。每个“page”应该有一个对应的 JavaScript 入口文件。其值应该是一个对象，对象的 key 是入口的名字，value 是：
 
-  - 一个指定了 `entry`, `template` 和 `filename` 的对象；
+  - 一个指定了 `entry`, `template`, `filename`, `title` 和 `chunks` 的对象 (除了 `entry` 之外都是可选的)；
   - 或一个指定其 `entry` 的字符串。
 
   ``` js
@@ -87,7 +107,13 @@ module.exports = {
         // 模板来源
         template: 'public/index.html',
         // 在 dist/index.html 的输出
-        filename: 'index.html'
+        filename: 'index.html',
+        // 当使用 title 选项时，
+        // template 中的 title 标签需要是 <title><%= htmlWebpackPlugin.options.title %></title>
+        title: 'Index Page',
+        // 在这个页面中包含的块，默认情况下会包含
+        // 提取出来的通用 chunk 和 vendor chunk。
+        chunks: ['chunk-vendors', 'chunk-common', 'index']
       },
       // 当使用只有入口的字符串格式时，
       // 模板会被推导为 `public/subpage.html`
@@ -104,11 +130,13 @@ module.exports = {
 
 ### lintOnSave
 
-- Type: `boolean`
+- Type: `boolean` | `error`
 - Default: `true`
 
   是否在开发环境下通过 [eslint-loader](https://github.com/webpack-contrib/eslint-loader) 在每次保存时 lint 代码。这个值会在 [`@vue/cli-plugin-eslint`](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-eslint) 被安装之后生效。
 
+  设置为 `true` 时，eslint-loader 在 webpack 的编译过程中只会触发警告，以避免中断开发流程。如果你希望换做触发错误 (例如在为生成环境构建时)，可以这样设置：`lintOnSave: 'error'`。
+
 ### runtimeCompiler
 
 - Type: `boolean`
@@ -132,6 +160,13 @@ module.exports = {
 
   如果你不需要生产环境的 source map，可以将其设置为 `false` 以加速生产环境构建。
 
+### corsUseCredentials
+
+- Type: `boolean`
+- Default: `false`
+
+  在现代模式下，生成的 HTML 会包含 `<script type="module">`，这需要[始终开启 CORS 才能被载入](https://jakearchibald.com/2017/es-modules-in-browsers/#always-cors)。默认情况下，它被处理为 `crossorigin="anonymous"`，将这个选项设置为 `true` 后则会换用 `crossorigin="use-credentials"`。
+
 ### configureWebpack
 
 - Type: `Object | Function`
@@ -161,15 +196,17 @@ module.exports = {
 
 ### css.extract
 
-- Type: `boolean`
-- Default: `true` (in production mode)
+- Type: `boolean | Object`
+- Default: 生产环境下是 `true`，开发环境下是 `false`
 
   是否将组件中的 CSS 提取至一个独立的 CSS 文件中 (而不是动态注入到 JavaScript 中的 inline 代码)。
 
-  同样当构建 Web Components 组件时它会默认被禁用 (样式是 inline 的并注入到了 shadowRoot 中)。
+  同样当构建 Web Components 组件时它总是会被禁用 (样式是 inline 的并注入到了 shadowRoot 中)。
 
   当作为一个库构建时，你也可以将其设置为 `false` 免得用户自己导入 CSS。
 
+  提取 CSS 在开发环境模式下是默认不开启的，因为它和 CSS 热重载不兼容。然而，你仍然可以将这个值显性地设置为 `true` 在所有情况下都强制提取。
+
 ### css.sourceMap
 
 - Type: `boolean`

docs/zh/dev-guide/plugin-dev.md

@@ -234,6 +234,33 @@ export default {
 <%# END_REPLACE %>
 ```
 
+#### 文件名都极端情况
+
+如果你想要渲染一个以点开头的模板文件 (例如 `.env`)，则需要遵循一个特殊的命名约定，因为以点开头的文件会在插件发布到 npm 的时候被忽略：
+
+```
+# 以点开头的模板需要使用下划线取代那个点：
+
+/generator/template/_env
+
+# 调用 api.render('./template') 会在项目目录中渲染成为：
+
+.env
+```
+
+同时这也意味着当你想渲染以下划线开头的文件时，同样需要遵循一个特殊的命名约定：
+
+```
+# 这种模板需要使用两个下划线来取代单个下划线：
+
+/generator/template/__variables.scss
+
+# 调用 api.render('./template') 会在项目目录中渲染成为：
+
+_variables.scss
+```
+
+
 ### 提示符
 
 #### 内建插件的提示符

docs/zh/dev-guide/ui-api.md

@@ -1,4 +1,4 @@
-# UI API
+# UI 插件 API
 
 这个 cli-ui 暴露一个 API，允许增强项目的配置和任务，也可以分享数据和在进程间进行通信。
 

docs/zh/dev-guide/ui-localization.md

@@ -34,14 +34,18 @@ API 的用法示例：
 ```js
 api.describeConfig({
   // vue-i18n 路径
-  description: 'my-plugin.config.foo'
+  description: 'com.my-name.my-plugin.config.foo'
 })
 ```
 
+::: danger 危险
+请确定为 id 设置正确的命名空间，因为它需要跨所有插件保持唯一。我们推荐使用[反向域名记号 (reverse domain name notation)](https://en.wikipedia.org/wiki/Reverse_domain_name_notation)。
+:::
+
 在组件中使用的示例：
 
 ```html
-<VueButton>{{ $t('my-plugin.actions.bar') }}</VueButton>
+<VueButton>{{ $t('com.my-name.my-plugin.actions.bar') }}</VueButton>
 ```
 
 如果你愿意的话，可以使用 `ClientAddonApi` 在一个客户端 addon 加载地区文件：

docs/zh/guide/README.md

@@ -4,6 +4,12 @@ sidebarDepth: 0
 
 # 介绍
 
+<Bit/>
+
+::: warning 警告
+这份文档是对应 `@vue/cli` **3.x** 版本的。老版本的 `vue-cli` 文档请移步[这里](https://github.com/vuejs/vue-cli/tree/v2#vue-cli--)。
+:::
+
 Vue CLI 是一个基于 Vue.js 进行快速开发的完整系统，提供：
 
 - 通过 `@vue/cli` 搭建交互式的项目脚手架。
@@ -14,6 +20,7 @@ Vue CLI 是一个基于 Vue.js 进行快速开发的完整系统，提供：
   - 可以通过项目内的配置文件进行配置；
   - 可以通过插件进行扩展。
 - 一个丰富的官方插件集合，集成了前端生态中最好的工具。
+- 一套完全图形化的创建和管理 Vue.js 项目的用户界面。
 
 Vue CLI 致力于将 Vue 生态中的工具基础标准化。它确保了各种构建工具能够基于智能的默认配置即可平稳衔接，这样你可以专注在撰写应用上，而不必花好几天去纠结配置的问题。与此同时，它也为每个工具提供了调整配置的灵活性，无需 eject。
 

docs/zh/guide/browser-compatibility.md

@@ -2,13 +2,13 @@
 
 ## browserslist
 
-你会发现 `package.json` 文件里有一个 `browserlist` 字段，指定里项目的目标浏览器的范围。这个值会被 [@babel/preset-env][babel-preset-env] 和 [Autoprefixer][autoprefixer] 用来确定需要转译的 JavaScript 特性和需要添加的 CSS 浏览器前缀。
+你会发现有 `package.json` 文件里的 `browserlist` 字段 (或一个单独的 `.browserslistrc` 文件)，指定了项目的目标浏览器的范围。这个值会被 [@babel/preset-env][babel-preset-env] 和 [Autoprefixer][autoprefixer] 用来确定需要转译的 JavaScript 特性和需要添加的 CSS 浏览器前缀。
 
 现在查阅[这里][browserslist]了解如何指定浏览器范围。
 
 ## Polyfill
 
-一个默认的 Vue CLI 项目会使用 [@vue/babel-preset-app][babel-preset-env]，它通过 `@babel/preset-env` 和 `browserslist` 配置来决定项目需要的 polyfill。
+一个默认的 Vue CLI 项目会使用 [@vue/babel-preset-app][babel-preset-app]，它通过 `@babel/preset-env` 和 `browserslist` 配置来决定项目需要的 polyfill。
 
 默认情况下，它会把 [`useBuiltIns: 'usage'`](https://new.babeljs.io/docs/en/next/babel-preset-env.html#usebuiltins-usage) 传递给 `@babel/preset-env`，这样它会根据源代码中出现的语言特性自动检测需要的 polyfill。这确保了最终包里 polyfill 数量的最小化。然而，这也意味着**如果其中一个依赖需要特殊的 polyfill，默认情况下 Babel 无法将其检测出来。**
 
@@ -62,6 +62,17 @@ Vue CLI 会产生两个应用的版本：一个现代版的包，面向支持 [E
 
 对于一个 Hello World 应用来说，现代版的包已经小了 16%。在生产环境下，现代版的包通常都会表现出显著的解析速度和运算速度，从而改善应用的加载性能。
 
+::: tip 提示
+`<script type="module">` [需要配合始终开启的 CORS 进行加载](https://jakearchibald.com/2017/es-modules-in-browsers/#always-cors)。这意味着你的服务器必须返回诸如 `Access-Control-Allow-Origin: *` 的有效的 CORS 头。如果你想要通过认证来获取脚本，可使用 [corsUseCredentials](../config/#corsusecredentials) 选项。
+
+同时，现代浏览器使用一段内联脚本来避免 Safari 10 重复加载脚本包，所以如果你在使用一套严格的 CSP，你需要这样显性地允许内联脚本：
+
+```
+Content-Security-Policy: script-src 'self' 'sha256-4RS22DYeB7U14dra4KcQYxmwt5HkOInieXK1NUMBmQI='
+```
+:::
+
 [autoprefixer]: https://github.com/postcss/autoprefixer
 [babel-preset-env]: https://new.babeljs.io/docs/en/next/babel-preset-env.html
+[babel-preset-app]: https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app
 [browserslist]: https://github.com/ai/browserslist

docs/zh/guide/build-targets.md

@@ -70,13 +70,15 @@ Web Components 模式不支持 IE11 及更低版本。[更多细节](https://git
 在 Web Components 模式中，Vue 是*外置的*。这意味着包中不会有 Vue，即便你在代码中导入了 Vue。这里的包会假设在页面中已经有一个可用的全局变量 `Vue`。
 :::
 
-你可以通过下面的命令将一个单独的入口构建为一个库：
+你可以通过下面的命令将一个单独的入口构建为一个 Web Components 组件：
 
 ```
 vue-cli-service build --target wc --name my-element [entry]
 ```
 
-这将会产生一个单独的 JavaScript 文件 (及其压缩后的版本) 将所有的东西都内联起来。当这个脚本被引入网页时，会注册自定义组件 `<my-element>`，其使用 `@vue/web-component-wrapper` 包裹了目标的 Vue 组件。这个包裹器会自动代理属性、特性、事件和插槽。请查阅 [`@vue/web-component-wrapper` 的文档](https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-web-component-wrapper/README.md)了解更多细节。
+注意这里的入口应该是一个 `*.vue` 文件。Vue CLI 将会把这个组件自动包裹并注册为 Web Components 组件，无需在 `main.js` 里做这件事。你也完全可以在开发时以一个 demo app 使用 `main.js`。
+
+该构建将会产生一个单独的 JavaScript 文件 (及其压缩后的版本) 将所有的东西都内联起来。当这个脚本被引入网页时，会注册自定义组件 `<my-element>`，其使用 `@vue/web-component-wrapper` 包裹了目标的 Vue 组件。这个包裹器会自动代理属性、特性、事件和插槽。请查阅 [`@vue/web-component-wrapper` 的文档](https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-web-component-wrapper/README.md)了解更多细节。
 
 **注意这个包依赖了在页面上全局可用的 `Vue`。**
 

docs/zh/guide/cli-service.md

@@ -29,10 +29,18 @@ yarn serve
 npx vue-cli-service serve
 ```
 
+::: tip 提示
+你可以通过 `vue ui` 命令使用 GUI 运行更多的特性脚本。
+:::
+
+这里有一个 GUI 的 Webpack Analyzer：
+
+![UI Webpack Analyzer](/ui-analyzer.png)
+
 ## vue-cli-service serve
 
 ```
-用法：vue-cli-service serve [options]
+用法：vue-cli-service serve [options] [entry]
 
 选项：