mirror of
https://github.com/vuejs/vue-cli.git
synced 2026-03-09 09:00:16 -05:00
docs(zh): update (#2016) [ci skip]
This commit is contained in:
勾三股四
@@ -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'
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
vue create my-project
|
||||
```
|
||||
|
||||
创建一个项目：
|
||||
|
||||
``` bash
|
||||
vue create my-project
|
||||
# OR
|
||||
vue ui
|
||||
```
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
|
||||
### 提示符
|
||||
|
||||
#### 内建插件的提示符
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# UI API
|
||||
# UI 插件 API
|
||||
|
||||
这个 cli-ui 暴露一个 API，允许增强项目的配置和任务，也可以分享数据和在进程间进行通信。
|
||||
|
||||
|
||||
@@ -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 加载地区文件：
|
||||
|
||||
@@ -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。
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`。**
|
||||
|
||||
|
||||
@@ -29,10 +29,18 @@ yarn serve
|
||||
npx vue-cli-service serve
|
||||
```
|
||||
|
||||
::: tip 提示
|
||||
你可以通过 `vue ui` 命令使用 GUI 运行更多的特性脚本。
|
||||
:::
|
||||
|
||||
这里有一个 GUI 的 Webpack Analyzer：
|
||||
|
||||
|
||||
|
||||
## vue-cli-service serve
|
||||
|
||||
```
|
||||
用法：vue-cli-service serve [options]
|
||||
用法：vue-cli-service serve [options] [entry]
|
||||
|
||||
选项：
|
||||
|
||||
|
||||
@@ -1,19 +1,5 @@
|
||||
# 创建一个项目
|
||||
|
||||
## 安装
|
||||
|
||||
::: tip Node 版本要求
|
||||
Vue CLI 需要 [Node.js](https://nodejs.org/) v8 或更高版本 (推荐 8.10.0+)。你可以使用 [nvm](https://github.com/creationix/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 在同一台机器上同时管理多个 Node 版本。
|
||||
:::
|
||||
|
||||
``` bash
|
||||
npm install -g @vue/cli
|
||||
# 或者
|
||||
yarn global add @vue/cli
|
||||
```
|
||||
|
||||
安装好之后，你就可以在命令后中访问 `vue` 命令了。运行 `vue` 会看到所有可用的命令构成的一段帮助信息，你可以通过它来确认安装是否成功。
|
||||
|
||||
## vue create
|
||||
|
||||
运行以下命令来创建一个新项目：
|
||||
@@ -22,6 +8,10 @@ yarn global add @vue/cli
|
||||
vue create hello-world
|
||||
```
|
||||
|
||||
::: warning 警告
|
||||
如果你在 Windows 上通过 minTTY 使用 Git Bash，交互提示符并不工作。你必须通过 `winpty vue.cmd create hello-world` 启动这个命令。
|
||||
:::
|
||||
|
||||
你会被提示选取一个 preset。你可以选默认的包含了基本的 Babel + ESLint 设置的 preset，也可以选“手动选择特性”来选取需要的特性。
|
||||
|
||||
|
||||
|
||||
@@ -25,6 +25,34 @@ $color = red;
|
||||
</style>
|
||||
```
|
||||
|
||||
### 自动化导入
|
||||
|
||||
如果你想自动化导入文件 (用于颜色、变量、mixin……)，你可以使用 [style-resources-loader](https://github.com/yenshih/style-resources-loader)。这里有一个关于 stylus 的在每个单文件组件和 stylus 文件中导入 `./src/styles/imports.styl` 的例子：
|
||||
|
||||
```js
|
||||
// vue.config.js
|
||||
const path = require('path')
|
||||
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
const types = ['vue-modules', 'vue', 'normal-modules', 'normal']
|
||||
types.forEach(type => addStyleResource(config.module.rule('stylus').oneOf(type)))
|
||||
},
|
||||
}
|
||||
|
||||
function addStyleResource (rule) {
|
||||
rule.use('style-resource')
|
||||
.loader('style-resources-loader')
|
||||
.options({
|
||||
patterns: [
|
||||
path.resolve(__dirname, './src/styles/imports.styl'),
|
||||
],
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
你也可以选择使用 [vue-cli-plugin-style-resources-loader](https://www.npmjs.com/package/vue-cli-plugin-style-resources-loader)。
|
||||
|
||||
## PostCSS
|
||||
|
||||
Vue CLI 内部使用了 PostCSS。
|
||||
@@ -82,8 +110,6 @@ module.exports = {
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
const fs = require('fs')
|
||||
|
||||
module.exports = {
|
||||
css: {
|
||||
loaderOptions: {
|
||||
|
||||
@@ -31,11 +31,61 @@ serve -s dist
|
||||
|
||||
如果你使用了 PWA 插件，那么应用必须架设在 HTTPS 上，这样 [Service Worker](https://developer.mozilla.org/zh-CN/docs/Web/API/Service_Worker_API) 才能被正确注册。
|
||||
|
||||
<!-- @todo: translation -->
|
||||
|
||||
## Platform Guides
|
||||
|
||||
(暂未翻译，此部分英文文档处于开放贡献中)
|
||||
|
||||
### GitHub Pages
|
||||
|
||||
> TODO | Open to contribution.
|
||||
1. Set correct `baseUrl` in `vue.config.js`.
|
||||
|
||||
If you are deploying to `https://<USERNAME>.github.io/`, you can omit `baseUrl` as it defaults to `"/"`.
|
||||
|
||||
If you are deploying to `https://<USERNAME>.github.io/<REPO>/`, (i.e. your repository is at `https://github.com/<USERNAME>/<REPO>`), set `baseUrl` to `"/<REPO>/"`. For example, if your repo name is "my-project", your `vue.config.js` should look like this:
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
baseUrl: process.env.NODE_ENV === 'production'
|
||||
? '/my-project/'
|
||||
: '/'
|
||||
}
|
||||
```
|
||||
|
||||
2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately) and run it to deploy:
|
||||
|
||||
``` bash{13,20,23}
|
||||
#!/usr/bin/env sh
|
||||
|
||||
# abort on errors
|
||||
set -e
|
||||
|
||||
# build
|
||||
npm run docs:build
|
||||
|
||||
# navigate into the build output directory
|
||||
cd docs/.vuepress/dist
|
||||
|
||||
# if you are deploying to a custom domain
|
||||
# echo 'www.example.com' > CNAME
|
||||
|
||||
git init
|
||||
git add -A
|
||||
git commit -m 'deploy'
|
||||
|
||||
# if you are deploying to https://<USERNAME>.github.io
|
||||
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master
|
||||
|
||||
# if you are deploying to https://<USERNAME>.github.io/<REPO>
|
||||
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
|
||||
|
||||
cd -
|
||||
```
|
||||
|
||||
::: tip
|
||||
You can also run the above script in your CI setup to enable automatic deployment on each push.
|
||||
:::
|
||||
|
||||
### GitLab Pages
|
||||
|
||||
@@ -78,7 +128,12 @@ Commit both the `.gitlab-ci.yml` and `vue.config.js` files before pushing to you
|
||||
|
||||
### Netlify
|
||||
|
||||
> TODO | Open to contribution.
|
||||
1. On Netlify, setup up a new project from GitHub with the following settings:
|
||||
|
||||
- **Build Command:** `npm run build` or `yarn build`
|
||||
- **Publish directory:** `dist`
|
||||
|
||||
2. Hit the deploy button!
|
||||
|
||||
Also checkout [vue-cli-plugin-netlify-lambda](https://github.com/netlify/vue-cli-plugin-netlify-lambda).
|
||||
|
||||
@@ -86,13 +141,68 @@ Also checkout [vue-cli-plugin-netlify-lambda](https://github.com/netlify/vue-cli
|
||||
|
||||
See [vue-cli-plugin-s3-deploy](https://github.com/multiplegeorges/vue-cli-plugin-s3-deploy).
|
||||
|
||||
### Azure
|
||||
|
||||
> TODO | Open to contribution.
|
||||
|
||||
### Firebase
|
||||
|
||||
> TODO | Open to contribution.
|
||||
Create a new Firebase project on your [Firebase console](https://console.firebase.google.com). Please refer to this [documentation](https://firebase.google.com/docs/web/setup) on how to setup your project.
|
||||
|
||||
Make sure you have installed [firebase-tools](https://github.com/firebase/firebase-tools) globally:
|
||||
|
||||
```
|
||||
npm install -g firebase-tools
|
||||
```
|
||||
|
||||
From the root of your project, initialize `firebase` using the command:
|
||||
|
||||
```
|
||||
firebase init
|
||||
```
|
||||
|
||||
Firebase will ask some questions on how to setup your project.
|
||||
|
||||
- Choose which Firebase CLI features you want to setup your project. Make sure to select `hosting`.
|
||||
- Select the default Firebase project for your project.
|
||||
- Set your `public` directory to `dist` (or where your build's output is) which will be uploaded to Firebase Hosting.
|
||||
|
||||
```javascript
|
||||
// firebase.json
|
||||
|
||||
{
|
||||
"hosting": {
|
||||
"public": "app"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Select `yes` to configure your project as a single-page app. This will create an `index.html` and on your `dist` folder and configure your `hosting` information.
|
||||
|
||||
```javascript
|
||||
// firebase.json
|
||||
|
||||
{
|
||||
"hosting": {
|
||||
"rewrites": [
|
||||
{
|
||||
"source": "**",
|
||||
"destination": "/index.html"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Run `npm run build` to build your project.
|
||||
|
||||
To deploy your project on Firebase Hosting, run the command:
|
||||
|
||||
```
|
||||
firebase deploy --only hosting
|
||||
```
|
||||
|
||||
If you want other Firebase CLI features you use on your project to be deployed, run `firebase deploy` without the `--only` option.
|
||||
|
||||
You can now access your project on `https://<YOUR-PROJECT-ID>.firebaseapp.com`.
|
||||
|
||||
Please refer to the [Firebase Documentation](https://firebase.google.com/docs/hosting/deploying) for more details.
|
||||
|
||||
### Now
|
||||
|
||||
@@ -108,4 +218,24 @@ See [vue-cli-plugin-s3-deploy](https://github.com/multiplegeorges/vue-cli-plugin
|
||||
|
||||
### Surge
|
||||
|
||||
> TODO | Open to contribution.
|
||||
To deploy with [Surge](http://surge.sh/) the steps are very straightforward.
|
||||
|
||||
First you would need to build your project by running `npm run build`. And if you haven't installed Surge's command line tool, you can simply do so by running the command:
|
||||
|
||||
```
|
||||
npm install --global surge
|
||||
```
|
||||
|
||||
Then cd into the `dist/` folder of your project and then run `surge` and follow the screen prompt. It will ask you to set up email and password if it is the first time you are using Surge. Confirm the project folder and type in your preferred domain and watch your project being deployed such as below.
|
||||
|
||||
```
|
||||
project: /Users/user/Documents/myawesomeproject/dist/
|
||||
domain: myawesomeproject.surge.sh
|
||||
upload: [====================] 100% eta: 0.0s (31 files, 494256 bytes)
|
||||
CDN: [====================] 100%
|
||||
IP: **.**.***.***
|
||||
|
||||
Success! - Published to myawesomeproject.surge.sh
|
||||
```
|
||||
|
||||
Verify your project is successfully published by Surge by visiting `myawesomeproject.surge.sh`, vola! For more setup details such as custom domains, you can visit [Surge's help page](https://surge.sh/help/).
|
||||
|
||||
@@ -59,10 +59,44 @@ module.exports = {
|
||||
}
|
||||
```
|
||||
|
||||
当 prefetch 插件被禁用时，你可以通过 webpack 的内联注释手动选定要提前获取的代码区块：
|
||||
|
||||
``` js
|
||||
import(/* webpackPrefetch: true */ './someAsyncComponent.vue')
|
||||
```
|
||||
|
||||
webpack 的运行时会在父级区块被加载之后注入 prefetch 链接。
|
||||
|
||||
::: tip 提示
|
||||
Prefetch 链接将会消耗带宽。如果你的应用很大且有很多 async chunk，而用户主要使用的是对带宽较敏感的移动端，那么你可能需要关掉 prefetch 链接。
|
||||
Prefetch 链接将会消耗带宽。如果你的应用很大且有很多 async chunk，而用户主要使用的是对带宽较敏感的移动端，那么你可能需要关掉 prefetch 链接并手动选择要提前获取的代码区块。
|
||||
:::
|
||||
|
||||
### 不生成 index
|
||||
|
||||
当基于已有的后端使用 Vue CLI 时，你可能不需要生成 `index.html`，这样生成的资源可以用于一个服务端渲染的页面。这时可以向 [`vue.config.js`](../config/#vue-config-js) 加入下列代码：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
// 去掉文件名中的 hash
|
||||
filenameHashing: false,
|
||||
// 删除 HTML 相关的 webpack 插件
|
||||
chainWebpack: config => {
|
||||
config.plugins.delete('html')
|
||||
config.plugins.delete('preload')
|
||||
config.plugins.delete('prefetch')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然而这样做并不是很推荐，因为：
|
||||
|
||||
- 硬编码的文件名不利于实现高效率的缓存控制。
|
||||
- 硬编码的文件名也无法很好的进行 code-splitting (代码分段)，因为无法用变化的文件名生成额外的 JavaScript 文件。
|
||||
- 硬编码的文件名无法在[现代模式](../guide/browser-compatibility.md#现代模式)下工作。
|
||||
|
||||
你应该考虑换用 [indexPath](../config/#indexpath) 选项将生成的 HTML 用作一个服务端框架的视图模板。
|
||||
|
||||
### 构建一个多页应用
|
||||
|
||||
不是每个应用都需要是一个单页应用。Vue CLI 支持使用 [`vue.config.js` 中的 `pages` 选项](../config/#pages)构建一个多页面的应用。构建好的应用将会在不同的入口之间高效共享通用的 chunk 以获得最佳的加载性能。
|
||||
|
||||
26
docs/zh/guide/installation.md
Normal file
26
docs/zh/guide/installation.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# 安装
|
||||
|
||||
::: danger 危险
|
||||
我们的包名由 `vue-cli` 改成了 `@vue/cli`。
|
||||
如果你已经全局安装了旧版本的 `vue-cli` (1.x 或 2.x)，你需要先通过 `npm uninstall vue-cli -g` 或 `yarn global remove vue-cli` 卸载它。
|
||||
:::
|
||||
|
||||
::: tip Node 版本要求
|
||||
Vue CLI 需要 [Node.js](https://nodejs.org/) 8.9 或更高版本 (推荐 8.11.0+)。你可以使用 [nvm](https://github.com/creationix/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 在同一台电脑中管理多个 Node 版本。
|
||||
:::
|
||||
|
||||
可以使用下列任一命令安装这个新的包：
|
||||
|
||||
``` bash
|
||||
npm install -g @vue/cli
|
||||
# OR
|
||||
yarn global add @vue/cli
|
||||
```
|
||||
|
||||
安装之后，你就可以在命令行中访问 `vue` 命令。你可以通过简单运行 `vue`，看看是否展示出了一份所有可用命令的帮助信息，来验证它是否安装成功。
|
||||
|
||||
你还可以用这个命令来检查其版本是否正确 (3.x)：
|
||||
|
||||
```bash
|
||||
vue --version
|
||||
```
|
||||
@@ -18,6 +18,13 @@ VUE_APP_SECRET=secret
|
||||
|
||||
被载入的变量将会对 `vue-cli-service` 的所有命令、插件和依赖可用。
|
||||
|
||||
::: tip 环境加载属性
|
||||
|
||||
为一个特定模式准备的环境文件的 (例如 `.env.production`) 将会比一般的环境文件 (例如 `.env`) 拥有更高的优先级。
|
||||
|
||||
此外，Vue CLI 启动时已经存在的环境变量拥有最高优先级，并不会被 `.env` 文件覆写。如果在环境中有默认的 `NODE_ENV`，你可能需要考虑移除它。
|
||||
:::
|
||||
|
||||
## 模式
|
||||
|
||||
**模式**是 Vue CLI 项目中一个重要的概念。默认情况下，一个 Vue CLI 项目有三个模式：
|
||||
@@ -74,6 +81,10 @@ console.log(process.env.VUE_APP_SECRET)
|
||||
|
||||
所有解析出来的环境变量都可以在 `public/index.html` 中以 [HTML 插值](./html-and-static-assets.md#插值)中介绍的方式使用。
|
||||
|
||||
::: tip 提示
|
||||
你可以在 `vue.config.js` 文件中计算环境变量。它们仍然需要以 `VUE_APP_` 前缀开头。这可以用于版本信息 `process.env.VUE_APP_VERSION = require('./package.json').version`
|
||||
:::
|
||||
|
||||
## 只在本地有效的变量
|
||||
|
||||
有的时候你可能有一些不应该提交到代码仓库中的变量，尤其是当你的项目托管在公共仓库时。这种情况下你应该使用一个 `.env.local` 文件取而代之。本地环境文件默认会被忽略，且出现在 `.gitignore` 中。
|
||||
|
||||
@@ -6,6 +6,10 @@ Vue CLI 使用了一套基于插件的架构。如果你查阅一个新创建项
|
||||
|
||||
基于插件的架构使得 Vue CLI 灵活且可扩展。如果你对开发一个插件感兴趣，请翻阅[插件开发指南](../dev-guide/plugin-dev.md)。
|
||||
|
||||
::: tip
|
||||
你可以通过 `vue ui` 命令使用 GUI 安装和管理插件。
|
||||
:::
|
||||
|
||||
### 在现有的项目中安装插件
|
||||
|
||||
每个 CLI 插件都会包含一个 (用来创建文件的) 生成器和一个 (用来调整 webpack 核心配置和注入命令的) 运行时插件。当你使用 `vue create` 来创建一个新项目的时候，有些插件会根据你选择的特性被预安装好。如果你想在一个已经被创建好的项目中安装一个插件，可以使用 `vue add` 命令：
|
||||
@@ -57,6 +61,46 @@ vue add vuex
|
||||
|
||||
如果一个插件已经被安装，你可以使用 `vue invoke` 命令跳过安装过程，只调用它的生成器。这个命令会接受和 `vue add` 相同的参数。
|
||||
|
||||
::: tip 提示
|
||||
如果出于一些原因你的插件列在了该项目之外的其它 `package.json` 文件里，你可以在自己项目的 `package.json` 里设置 `vuePlugins.resolveFrom` 选项指向包含其它 `package.json` 的文件夹。
|
||||
|
||||
例如，如果你有一个 `.config/package.json` 文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"vuePlugins": {
|
||||
"resolveFrom": ".config"
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 项目本地的插件
|
||||
|
||||
如果你需要在项目里直接访问插件 API 而不需要创建一个完整的插件，你可以在 `package.json` 文件中使用 `vuePlugins.service` 选项：
|
||||
|
||||
```json
|
||||
{
|
||||
"vuePlugins": {
|
||||
"service": ["my-commands.js"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
每个文件都需要暴露一个函数，将插件 API 作为第一个参数携带。关于插件 API 的更多信息可以查阅[插件开发指南](../dev-guide/plugin-dev.md)。
|
||||
|
||||
你也可以通过 `vuePlugins.ui` 选项添加像 UI 插件一样工作的文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"vuePlugins": {
|
||||
"ui": ["my-ui.js"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
更多信息请阅读 [UI 插件 API](../dev-guide/ui-api.md)。
|
||||
|
||||
## Preset
|
||||
|
||||
一个 Vue CLI preset 是一个包含创建新项目所需预定义选项和插件的 JSON 对象，让用户无需在命令提示中选择它们。
|
||||
|
||||
@@ -52,7 +52,7 @@ webpack 内部的配置是通过 [webpack-chain](https://github.com/mozilla-neut
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
config.module
|
||||
.rule('vue')
|
||||
.use('vue-loader')
|
||||
.loader('vue-loader')
|
||||
|
||||
Reference in New Issue
Block a user