mirror of
https://github.com/vuejs/vue-cli.git
synced 2026-04-23 13:29:09 -05:00
[doc] Chinese docs translation (#1786)
This commit is contained in:
勾三股四
@@ -4,7 +4,12 @@ module.exports = {
|
||||
lang: 'en-US',
|
||||
title: 'Vue CLI 3',
|
||||
description: '🛠️ Standard Tooling for Vue.js Development'
|
||||
}
|
||||
},
|
||||
'/zh/': {
|
||||
lang: 'zh-CN',
|
||||
title: 'Vue CLI',
|
||||
description: '🛠️ Vue.js 开发的标准工具'
|
||||
},
|
||||
},
|
||||
serviceWorker: true,
|
||||
theme: 'vue',
|
||||
@@ -97,6 +102,82 @@ module.exports = {
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
'/zh/': {
|
||||
label: '简体中文',
|
||||
selectText: '选择语言',
|
||||
lastUpdated: '上次编辑时间',
|
||||
editLinkText: '在 GitHub 上编辑此页',
|
||||
nav: [
|
||||
{
|
||||
text: '指南',
|
||||
link: '/zh/guide/'
|
||||
},
|
||||
{
|
||||
text: '配置参考',
|
||||
link: '/zh/config/'
|
||||
},
|
||||
{
|
||||
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: '插件',
|
||||
items: [
|
||||
{ text: 'Babel', link: 'https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-cli-plugin-babel/README.md' },
|
||||
{ text: 'Typescript', link: 'https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-cli-plugin-typescript/README.md' },
|
||||
{ text: 'ESLint', link: 'https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-cli-plugin-eslint/README.md' },
|
||||
{ text: 'PWA', link: 'https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-cli-plugin-pwa/README.md' },
|
||||
{ text: 'Jest', link: 'https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-cli-plugin-unit-jest/README.md' },
|
||||
{ text: 'Mocha', link: 'https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-cli-plugin-unit-mocha/README.md' },
|
||||
{ text: 'Cypress', link: 'https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-cli-plugin-e2e-cypress/README.md' },
|
||||
{ text: 'Nightwatch', link: 'https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-cli-plugin-e2e-nightwatch/README.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '更新记录',
|
||||
link: 'https://github.com/vuejs/vue-cli/blob/dev/CHANGELOG.md'
|
||||
}
|
||||
],
|
||||
sidebar: {
|
||||
'/zh/guide/': [
|
||||
'/zh/guide/',
|
||||
{
|
||||
title: 'CLI',
|
||||
collapsable: false,
|
||||
children: [
|
||||
'/zh/guide/creating-a-project',
|
||||
'/zh/guide/prototyping',
|
||||
'/zh/guide/plugins-and-presets'
|
||||
]
|
||||
},
|
||||
{
|
||||
title: '开发',
|
||||
collapsable: false,
|
||||
children: [
|
||||
'/zh/guide/cli-service',
|
||||
'/zh/guide/browser-compatibility',
|
||||
'/zh/guide/html-and-static-assets',
|
||||
'/zh/guide/css',
|
||||
'/zh/guide/webpack',
|
||||
'/zh/guide/mode-and-env',
|
||||
'/zh/guide/build-targets',
|
||||
'/zh/guide/deployment'
|
||||
]
|
||||
}
|
||||
],
|
||||
'/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'
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
home: true
|
||||
heroImage: /logo.png
|
||||
actionText: 起步 →
|
||||
actionLink: /zh/guide/
|
||||
features:
|
||||
- title: 功能丰富
|
||||
details: 对 Babel、TypeScript、ESLint、PostCSS、PWA、单元测试和 End-to-end 测试提供开箱即用的支持。
|
||||
- title: 易于扩展
|
||||
details: 它的插件系统可以让社区根据常见需求构建和共享可复用的解决方案。
|
||||
- title: 无需 Eject
|
||||
details: Vue CLI 完全是可配置的，无需 eject。这样你的项目就可以长期保持更新了。
|
||||
- title: 基于 CLI 的图形化界面
|
||||
details: 通过配套的图形化界面创建、开发和管理你的项目。
|
||||
- title: 即刻创建原型
|
||||
details: 用单个 Vue 文件即刻实践新的灵感。
|
||||
- title: 面向未来
|
||||
details: 为现代浏览器轻松产出原生的 ES2015 代码，或将你的 Vue 组件构建为原生的 Web Components 组件。
|
||||
footer: MIT Licensed | Copyright © 2018-present Evan You
|
||||
---
|
||||
|
||||
## 起步
|
||||
|
||||
``` bash
|
||||
npm install -g @vue/cli
|
||||
# OR
|
||||
yarn global add @vue/cli
|
||||
|
||||
vue create my-project
|
||||
```
|
||||
@@ -0,0 +1,334 @@
|
||||
---
|
||||
sidebar: auto
|
||||
---
|
||||
|
||||
# 配置参考
|
||||
|
||||
## 全局 CLI 配置
|
||||
|
||||
有些针对 `@vue/cli` 的全局配置，例如你惯用的包管理器和你本地保存的 preset，都保存在 home 目录下一个名叫 `.vuerc` 的 JSON 文件。你可以用编辑器直接编辑这个文件来更改已保存的选项。
|
||||
|
||||
## 目标浏览器
|
||||
|
||||
请查阅指南中的[浏览器兼容性](../guide/browser-compatibility.md#browserslist)章节。
|
||||
|
||||
## vue.config.js
|
||||
|
||||
`vue.config.js` 是一个可选的配置文件，如果项目的 (和 `package.json` 同级的) 根目录中存在这个文件，那么它会被 `@vue/cli-service` 自动加载。你也可以使用 `package.json` 中的 `vue` 字段，但是注意这种写法需要你严格遵照 JSON 的格式来写。
|
||||
|
||||
这个文件应该导出一个包含了选项的对象：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
// 选项...
|
||||
}
|
||||
```
|
||||
|
||||
### baseUrl
|
||||
|
||||
- Type: `string`
|
||||
- Default: `'/'`
|
||||
|
||||
应用会被部署到的地方的基础 URL。默认情况下 Vue CLI 假设应用会被部署在一个域名的根，例如 `https://www.my-app.com/`。如果应用被部署在一个子路径上，你就需要用这个选项指定这个子路径。例如，如果你的应用被部署在 `https://www.my-app.com/my-app/`，则设置 `baseUrl` 为 `/my-app/`。
|
||||
|
||||
你必须正确地设置这个值以使生产环境中静态资源加载正确。
|
||||
|
||||
这个值在开发环境下同样生效。如果你想把开发服务器架设在根路径，你可以使用一个条件式的值：
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
baseUrl: process.env.NODE_ENV === 'production'
|
||||
? '/production-sub-path/'
|
||||
: '/'
|
||||
}
|
||||
```
|
||||
|
||||
这个值也可以被设置为空字符串 (`''`) 这样所有的资源都会被链接为相对路径，这样打出来的包可以用在类似 Cordova hybrid 应用的文件系统中。需要注意的生成的 CSS 文件要始终放在输出路径的根部，以确保 CSS 中的 URL 正常工作。
|
||||
|
||||
::: tip 提示
|
||||
请始终使用 `baseUrl` 而不要修改 webpack 的 `output.publicPath`。
|
||||
:::
|
||||
|
||||
### outputDir
|
||||
|
||||
- Type: `string`
|
||||
- Default: `'dist'`
|
||||
|
||||
当运行 `vue-cli-service build` 时生成的生产环境构建文件的目录。注意目标目录在构建之前会被清除 (构建时传入 `--no-clean` 可关闭该行为)。
|
||||
|
||||
::: tip 提示
|
||||
请始终使用 `outputDir` 而不要修改 webpack 的 `output.path`。
|
||||
:::
|
||||
|
||||
### assetsDir
|
||||
|
||||
- Type: `string`
|
||||
- Default: `''`
|
||||
|
||||
放置生成的静态资源 (js、css、img、fonts) 的目录。
|
||||
|
||||
### pages
|
||||
|
||||
- Type: `Object`
|
||||
- Default: `undefined`
|
||||
|
||||
在 multi-page 模式下构建应用。每个“page”应该有一个对应的 JavaScript 入口文件。其值应该是一个对象，对象的 key 是入口的名字，value 是：
|
||||
|
||||
- 一个指定了 `entry`, `template` 和 `filename` 的对象；
|
||||
- 或一个指定其 `entry` 的字符串。
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
pages: {
|
||||
index: {
|
||||
// page 的入口
|
||||
entry: 'src/index/main.js',
|
||||
// 模板来源
|
||||
template: 'public/index.html',
|
||||
// 在 dist/index.html 的输出
|
||||
filename: 'index.html'
|
||||
},
|
||||
// 当使用只有入口的字符串格式时，
|
||||
// 模板会被推导为 `public/subpage.html`
|
||||
// 并且如果找不到的话，就回退到 `public/index.html`。
|
||||
// 输出文件名会被推导为 `subpage.html`。
|
||||
subpage: 'src/subpage/main.js'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: tip 提示
|
||||
当在 multi-page 模式下构建时，webpack 配置会包含不一样的插件 (这时会存在多个 `html-webpack-plugin` 和 `preload-webpack-plugin` 的实例)。如果你试图修改这些插件的选项，请确认运行 `vue inspect`。
|
||||
:::
|
||||
|
||||
### lintOnSave
|
||||
|
||||
- Type: `boolean`
|
||||
- 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) 被安装之后生效。
|
||||
|
||||
### runtimeCompiler
|
||||
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
是否使用包含运行时编译器的 Vue 构建版本。设置为 `true` 后你就可以在 Vue 组件中使用 `template` 选项了，但是这会让你的应用额外增加 10kb 左右。
|
||||
|
||||
更多细节可查阅：[Runtime + Compiler vs. Runtime only](https://cn.vuejs.org/v2/guide/installation.html#运行时-编译器-vs-只包含运行时)。
|
||||
|
||||
### transpileDependencies
|
||||
|
||||
- Type: `Array<string | RegExp>`
|
||||
- Default: `[]`
|
||||
|
||||
默认情况下 `babel-loader` 会忽略所有 `node_modules` 中的文件。如果你想要通过 Babel 显式转译一个依赖，可以在这个选项中列出来。
|
||||
|
||||
### productionSourceMap
|
||||
|
||||
- Type: `boolean`
|
||||
- Default: `true`
|
||||
|
||||
如果你不需要生产环境的 source map，可以将其设置为 `false` 以加速生产环境构建。
|
||||
|
||||
### configureWebpack
|
||||
|
||||
- Type: `Object | Function`
|
||||
|
||||
如果这个值是一个对象，则会通过 [webpack-merge](https://github.com/survivejs/webpack-merge) 合并到最终的配置中。
|
||||
|
||||
如果这个值是一个函数，则会接收被解析的配置作为参数。该函数及可以修改配置并不返回任何东西，也可以返回一个被克隆或合并过的配置版本。
|
||||
|
||||
更多细节可查阅：[配合 webpack > 简单的配置方式](../guide/webpack.md#简单的配置方式)
|
||||
|
||||
### chainWebpack
|
||||
|
||||
- Type: `Function`
|
||||
|
||||
是一个函数，会接收一个基于 [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain) 的 `ChainableConfig` 实例。允许对内部的 webpack 配置进行更细粒度的修改。
|
||||
|
||||
更多细节可查阅：[配合 webpack > 链式操作](../guide/webpack.md#链式操作-高级)
|
||||
|
||||
### css.modules
|
||||
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
默认情况下，只有 `*.module.[ext]` 结尾的文件才会被视作 CSS Modules 模块。设置为 `true` 后你就可以去掉文件名中的 `.module` 并将所有的 `*.(css|scss|sass|less|styl(us)?)` 文件视为 CSS Modules 模块。
|
||||
|
||||
更多细节可查阅：[配合 CSS > CSS Modules](../guide/css.md#css-modules)
|
||||
|
||||
### css.extract
|
||||
|
||||
- Type: `boolean`
|
||||
- Default: `true` (in production mode)
|
||||
|
||||
是否将组件中的 CSS 提取至一个独立的 CSS 文件中 (而不是动态注入到 JavaScript 中的 inline 代码)。
|
||||
|
||||
同样当构建 Web Components 组件时它会默认被禁用 (样式是 inline 的并注入到了 shadowRoot 中)。
|
||||
|
||||
当作为一个库构建时，你也可以将其设置为 `false` 免得用户自己导入 CSS。
|
||||
|
||||
### css.sourceMap
|
||||
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
是否为 CSS 开启 source map。设置为 `true` 之后可能会影响构建的性能。
|
||||
|
||||
### css.loaderOptions
|
||||
|
||||
- Type: `Object`
|
||||
- Default: `{}`
|
||||
|
||||
向 CSS 相关的 loader 传递选项。例如：
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
css: {
|
||||
loaderOptions: {
|
||||
css: {
|
||||
// 这里的选项会传递给 css-loader
|
||||
},
|
||||
postcss: {
|
||||
// 这里的选项会传递给 postcss-loader
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
支持的 loader 有：
|
||||
|
||||
- [css-loader](https://github.com/webpack-contrib/css-loader)
|
||||
- [postcss-loader](https://github.com/postcss/postcss-loader)
|
||||
- [sass-loader](https://github.com/webpack-contrib/sass-loader)
|
||||
- [less-loader](https://github.com/webpack-contrib/less-loader)
|
||||
- [stylus-loader](https://github.com/shama/stylus-loader)
|
||||
|
||||
更多细节可查阅：[向预处理器 Loader 传递选项](../guide/css.html#向预处理器-loader-传递选项)
|
||||
|
||||
::: tip 提示
|
||||
我们倾向于使用 `chainWebpack` 手动修改指定的 loader，因为这些选项需要同时应用在相应 loader 出现的多个地方。
|
||||
:::
|
||||
|
||||
### devServer
|
||||
|
||||
- Type: `Object`
|
||||
|
||||
[所有 `webpack-dev-server` 的选项](https://webpack.js.org/configuration/dev-server/)都支持。注意：
|
||||
|
||||
- 有些值像 `host`、`port` 和 `https` 可能会被命令行参数覆写。
|
||||
|
||||
- 有些值像 `publicPath` 和 `historyApiFallback` 不应该被修改，因为它们需要和开发服务器的 [baseUrl](#baseurl) 同步以保障正常的工作。
|
||||
|
||||
### devServer.proxy
|
||||
|
||||
- Type: `string | Object`
|
||||
|
||||
如果你的前端应用和后端 API 服务器没有运行在同一个主机上，你需要在开发环境下将 API 请求代理到 API 服务器。这个问题可以通过 `vue.config.js` 中的 `devServer.proxy` 选项来配置。
|
||||
|
||||
`devServer.proxy` 可以是一个指向开发环境 API 服务器的字符串：
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
devServer: {
|
||||
proxy: 'http://localhost:4000'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这会告诉开发服务器将任何未知请求 (没有匹配到静态文件的请求) 代理到`http://localhost:4000`。
|
||||
|
||||
如果你想要更多的代理控制行为，也可以使用一个 `path: options` 成对的对象。完整的选项可以查阅 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware#proxycontext-config) 。
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
devServer: {
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: '<url>',
|
||||
ws: true,
|
||||
changeOrigin: true
|
||||
},
|
||||
'/foo': {
|
||||
target: '<other_url>'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### parallel
|
||||
|
||||
- Type: `boolean`
|
||||
- Default: `require('os').cpus().length > 1`
|
||||
|
||||
是否为 Babel 或 TypeScript 使用 `thread-loader`。
|
||||
|
||||
### pwa
|
||||
|
||||
- Type: `Object`
|
||||
|
||||
向 [PWA 插件](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-pwa)传递选项。
|
||||
|
||||
### pluginOptions
|
||||
|
||||
- Type: `Object`
|
||||
|
||||
这是一个不进行任何 schema 验证的对象，因此它可以用来传递任何第三方插件选项。例如：
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
pluginOptions: {
|
||||
foo: {
|
||||
// 插件可以作为 `options.pluginOptions.foo` 访问这些选项。
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Babel
|
||||
|
||||
Babel 可以通过 `babel.config.js` 进行配置。
|
||||
|
||||
::: tip
|
||||
Vue CLI 使用了 Babel 7 中的新配置格式 `babel.config.js`。和 `.babelrc` 或 `package.json` 中的 `babel` 字段不同，这个配置文件不会使用基于文件位置的方案，而是会一致地运用到项目根目录以下的所有文件，包括 `node_modules` 内部的依赖。我们推荐在 Vue CLI 项目中始终使用 `babel.config.js` 取代其它格式。
|
||||
:::
|
||||
|
||||
所有的 Vue CLI 应用都使用 `@vue/babel-preset-app`，它包含了 `babel-preset-env`、JSX 支持以及为最小化包体积优化过的配置。通过[它的文档](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app)可以查阅到更多细节和 preset 选项。
|
||||
|
||||
同时查阅指南中的 [Polyfill](../guide/browser-compatibility.md#polyfill) 章节。
|
||||
|
||||
## ESLint
|
||||
|
||||
ESLint 可以通过 `.eslintrc` 或 `pacakge.json` 中的 `eslintConfig` 字段来配置。
|
||||
|
||||
更多细节可查阅 [@vue/cli-plugin-eslint](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-eslint)。
|
||||
|
||||
## TypeScript
|
||||
|
||||
TypeScript 可以通过 `tsconfig.json` 来配置。
|
||||
|
||||
更多细节可查阅 [@vue/cli-plugin-typescript](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-typescript)。
|
||||
|
||||
## 单元测试
|
||||
|
||||
### Jest
|
||||
|
||||
更多细节可查阅 [@vue/cli-plugin-unit-jest](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-jest)。
|
||||
|
||||
### Mocha (配合 `mocha-webpack`)
|
||||
|
||||
更多细节可查阅 [@vue/cli-plugin-unit-mocha](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-mocha)。
|
||||
|
||||
## E2E 测试
|
||||
|
||||
### Cypress
|
||||
|
||||
更多细节可查阅 [@vue/cli-plugin-e2e-cypress](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-cypress)。
|
||||
|
||||
### Nightwatch
|
||||
|
||||
更多细节可查阅 [@vue/cli-plugin-e2e-nightwatch](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch)。
|
||||
@@ -0,0 +1,311 @@
|
||||
---
|
||||
sidebarDepth: 3
|
||||
---
|
||||
|
||||
# 插件开发指南
|
||||
|
||||
## 核心概念
|
||||
|
||||
系统里有两个主要的部分：
|
||||
|
||||
- `@vue/cli`：全局安装的，暴露 `vue create <app>` 命令；
|
||||
- `@vue/cli-service`：局部安装，暴露 `vue-cli-service` 命令。
|
||||
|
||||
两者皆应用了基于插件的架构。
|
||||
|
||||
### Creator
|
||||
|
||||
[Creator][creator-class] 是调用 `vue create <app>` 时创建的类。负责偏好提示符、调用 generator 和安装依赖。
|
||||
|
||||
### Service
|
||||
|
||||
[Service][service-class] 是调用 `vue-cli-service <command> [...args]` 时创建的类。负责管理内部的 webpack 配置、暴露服务和构建项目的命令等。
|
||||
|
||||
### CLI 插件
|
||||
|
||||
CLI 插件是一个可以为 `@vue/cli` 项目添加额外特性的 npm 包。它应该始终包含一个 [Service 插件](#service-插件)作为其主要导出，且可选的包含一个 [Generator](#generator) 和一个 [Prompt 文件](#第三方插件的提示符)。
|
||||
|
||||
一个典型的 CLI 插件的目录结构看起来是这样的：
|
||||
|
||||
```
|
||||
.
|
||||
├── README.md
|
||||
├── generator.js # generator (可选)
|
||||
├── prompts.js # prompt 文件 (可选)
|
||||
├── index.js # service 插件
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Service 插件
|
||||
|
||||
Service 插件会在一个 Service 实例被创建时自动加载——比如每次 `vue-cli-service` 命令在项目中被调用时。
|
||||
|
||||
注意我们这里讨论的“service 插件”的概念要比发布为一个 npm 包的“CLI 插件”的要更窄。前者涉及一个会被 `@vue/cli-service` 在初始化时加载的模块，也经常是后者的一部分。
|
||||
|
||||
此外，`@vue/cli-service` 的[内建命令][commands]和[配置模块][config]也是全部以 service 插件实现的。
|
||||
|
||||
一个 service 插件应该导出一个函数，这个函数接受两个参数：
|
||||
|
||||
- 一个 [PluginAPI][plugin-api] 实例
|
||||
|
||||
- 一个包含 `vue.config.js` 内指定的项目本地选项的对象，或者在 `package.json` 内的 `vue` 字段。
|
||||
|
||||
这个 API 允许 service 插件针对不同的环境扩展/修改内部的 webpack 配置，并向 `vue-cli-service` 注入额外的命令。例如：
|
||||
|
||||
``` js
|
||||
module.exports = (api, projectOptions) => {
|
||||
api.chainWebpack(webpackConfig => {
|
||||
// 通过 webpack-chain 修改 webpack 配置
|
||||
})
|
||||
|
||||
api.configureWebpack(webpackConfig => {
|
||||
// 修改 webpack 配置
|
||||
// 或返回通过 webpack-merge 合并的配置对象
|
||||
})
|
||||
|
||||
api.registerCommand('test', args => {
|
||||
// 注册 `vue-cli-service test`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
#### 为命令指定模式
|
||||
|
||||
<!-- 对于环境变量来说，有一个值得注意的重要的事情，就是了解它们何时被解析。一般情况下，像 `vue-cli-service serve` 或 `vue-cli-service build` 这样的命令会始终调用 `api.setMode()` 作为它的第一件事。然而，这也意味着这些环境变量可能在 service 插件被调用的时候还不可用： -->
|
||||
> 注意：插件设置模式的方式从 beta.10 开始已经改变了。
|
||||
|
||||
如果一个已注册的插件命令需要运行在特定的默认模式下，则该插件需要通过 `module.exports.defaultModes` 以 `{ [commandName]: mode }` 的形式来暴露：
|
||||
|
||||
``` js
|
||||
module.exports = api => {
|
||||
api.registerCommand('build', () => {
|
||||
// ...
|
||||
})
|
||||
}
|
||||
|
||||
module.exports.defaultModes = {
|
||||
build: 'production'
|
||||
}
|
||||
```
|
||||
|
||||
这是因为我们需要在加载环境变量之前知道该命令的预期模式，所以需要提前加载用户选项/应用插件。
|
||||
|
||||
#### 在插件中解析 webpack 配置
|
||||
|
||||
一个插件可以通过调用 `api.resolveWebpackConfig()` 取回解析好的 webpack 配置。每次调用都会新生成一个 webpack 配置用来在需要时进一步修改。
|
||||
|
||||
``` js
|
||||
module.exports = api => {
|
||||
api.registerCommand('my-build', args => {
|
||||
const configA = api.resolveWebpackConfig()
|
||||
const configB = api.resolveWebpackConfig()
|
||||
|
||||
// 针对不同的目的修改 `configA` 和 `configB`...
|
||||
})
|
||||
}
|
||||
|
||||
// 请确保为正确的环境变量指定默认模式
|
||||
module.exports.defaultModes = {
|
||||
'my-build': 'production'
|
||||
}
|
||||
```
|
||||
|
||||
或者，一个插件也可以通过调用 `api.resolveChainableWebpackConfig()` 获得一个新生成的[链式配置](https://github.com/mozilla-neutrino/webpack-chain)：
|
||||
|
||||
``` js
|
||||
api.registerCommand('my-build', args => {
|
||||
const configA = api.resolveChainableWebpackConfig()
|
||||
const configB = api.resolveChainableWebpackConfig()
|
||||
|
||||
// 针对不同的目的链式修改 `configA` 和 `configB`...
|
||||
|
||||
const finalConfigA = configA.toConfig()
|
||||
const finalConfigB = configB.toConfig()
|
||||
})
|
||||
```
|
||||
|
||||
#### 第三方插件的自定义选项
|
||||
|
||||
`vue.config.js` 的导出将会[通过一个 schema 的验证](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-service/lib/options.js#L3)以避免笔误和错误的配置值。然而，一个第三方插件仍然允许用户通过 `pluginOptions` 字段配置其行为。例如，对于下面的 `vue.config.js`：
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
pluginOptions: {
|
||||
foo: { /* ... */ }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
该第三方插件可以读取 `projectOptions.pluginOptions.foo` 来做条件式的决定配置。
|
||||
|
||||
### Generator
|
||||
|
||||
一个发布为 npm 包的 CLI 插件可以包含一个 `generator.js` 或 `generator/index.js` 文件。插件内的 generator 将会在两种场景下被调用：
|
||||
|
||||
- 在一个项目的初始化创建过程中，如果 CLI 插件作为项目创建 preset 的一部分被安装。
|
||||
|
||||
- 插件在项目创建好之后通过 `vue invoke` 独立调用时被安装。
|
||||
|
||||
这里的 [GeneratorAPI][generator-api] 允许一个 generator 向 `package.json` 注入额外的依赖或字段，并向项目中添加文件。
|
||||
|
||||
一个 generator 应该导出一个函数，这个函数接收三个参数：
|
||||
|
||||
1. 一个 `GeneratorAPI` 实例：
|
||||
|
||||
2. 这个插件的 generator 选项。这些选项会在项目创建提示符过程中被解析，或从一个保存在 `~/.vuerc` 中的 preset 中加载。例如，如果保存好的 `~/.vuerc` 像如下的这样：
|
||||
|
||||
``` json
|
||||
{
|
||||
"presets" : {
|
||||
"foo": {
|
||||
"plugins": {
|
||||
"@vue/cli-plugin-foo": { "option": "bar" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果用户使用 preset `foo` 创建了一个项目，那么 `@vue/cli-plugin-foo` 的 generator 就会收到 `{ option: 'bar' }` 作为第二个参数。
|
||||
|
||||
对于一个第三方插件来说，该选项将会解析自提示符或用户执行 `vue invoke` 时的命令行参数中 (详见[第三方插件的提示符](#第三方插件的提示符))。
|
||||
|
||||
3. 整个 preset (`presets.foo`) 将会作为第三个参数传入。
|
||||
|
||||
**示例：**
|
||||
|
||||
``` js
|
||||
module.exports = (api, options, rootOptions) => {
|
||||
// 修改 `package.json` 里的字段
|
||||
api.extendPackage({
|
||||
scripts: {
|
||||
test: 'vue-cli-service test'
|
||||
}
|
||||
})
|
||||
|
||||
// 复制并用 ejs 渲染 `./template` 内所有的文件
|
||||
api.render('./template')
|
||||
|
||||
if (options.foo) {
|
||||
// 有条件地生成文件
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Generator 的模板处理
|
||||
|
||||
当你调用 `api.render('./template')` 时，该 generator 将会使用 [EJS](https://github.com/mde/ejs) 渲染 `./template` 中的文件 (相对于 generator 中的文件路径进行解析)
|
||||
|
||||
此外，你可以使用 YAML 前置元信息继承并替换已有的模板文件的一部分：
|
||||
|
||||
``` ejs
|
||||
---
|
||||
extend: '@vue/cli-service/generator/template/src/App.vue'
|
||||
replace: !!js/regexp /<script>[^]*?<\/script>/
|
||||
---
|
||||
|
||||
<script>
|
||||
export default {
|
||||
// 替换默认脚本
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
你也可以完成多处替换，当然你需要将要替换的字符串用 `<%# REPLACE %>` 和 `<%# END_REPLACE %>` 块包裹起来：
|
||||
|
||||
``` ejs
|
||||
---
|
||||
extend: '@vue/cli-service/generator/template/src/App.vue'
|
||||
replace:
|
||||
- !!js/regexp /欢迎来到你的 Vue\.js 应用/
|
||||
- !!js/regexp /<script>[^]*?<\/script>/
|
||||
---
|
||||
|
||||
<%# REPLACE %>
|
||||
替换欢迎信息
|
||||
<%# END_REPLACE %>
|
||||
|
||||
<%# REPLACE %>
|
||||
<script>
|
||||
export default {
|
||||
// 替换默认脚本
|
||||
}
|
||||
</script>
|
||||
<%# END_REPLACE %>
|
||||
```
|
||||
|
||||
### 提示符
|
||||
|
||||
#### 内建插件的提示符
|
||||
|
||||
只有内建插件可以定制创建新项目时的初始化提示符，且这些提示符模块放置在 [`@vue/cli` 包的内部][prompt-modules]。
|
||||
|
||||
一个提示符模块应该导出一个函数，这个函数接收一个 [PromptModuleAPI][prompt-api] 实例。这些提示符的底层使用 [inquirer](https://github.com/SBoudrias/Inquirer.js) 进行展示：
|
||||
|
||||
``` js
|
||||
module.exports = api => {
|
||||
// 一个特性对象应该是一个有效的 inquirer 选择对象
|
||||
api.injectFeature({
|
||||
name: 'Some great feature',
|
||||
value: 'my-feature'
|
||||
})
|
||||
|
||||
// injectPrompt 期望接收一个有效的 inquirer 提示符对象
|
||||
api.injectPrompt({
|
||||
name: 'someFlag',
|
||||
// 确认提示符只在用户已经选取了特性的时候展示
|
||||
when: answers => answers.features.include('my-feature'),
|
||||
message: 'Do you want to turn on flag foo?',
|
||||
type: 'confirm'
|
||||
})
|
||||
|
||||
// 当所有的提示符都完成之后，将你的插件注入到
|
||||
// 即将传递给 Generator 的 options 中
|
||||
api.onPromptComplete((answers, options) => {
|
||||
if (answers.features.includes('my-feature')) {
|
||||
options.plugins['vue-cli-plugin-my-feature'] = {
|
||||
someFlag: answers.someFlag
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
#### 第三方插件的提示符
|
||||
|
||||
第三方插件通常会在一个项目创建完毕后被手动安装，且用户将会通过调用 `vue invoke` 来初始化这个插件。如果这个插件在其根目录包含一个 `prompt.js`，那么它将会用在该插件被初始化调用的时候。这个文件应该导出一个用于 Inquirer.js 的[问题](https://github.com/SBoudrias/Inquirer.js#question)的数组。这些被解析的答案对象会作为选项被传递给插件的 generator。
|
||||
|
||||
或者，用户可以通过在命令行传递选项来跳过提示符直接初始化插件，比如：
|
||||
|
||||
``` bash
|
||||
vue invoke my-plugin --mode awesome
|
||||
```
|
||||
|
||||
## 发布插件
|
||||
|
||||
为了让一个 CLI 插件能够被其它开发者使用，你必须遵循 `vue-cli-plugin-<name>` 的命名约定将其发布到 npm 上。插件遵循命名约定之后就可以：
|
||||
|
||||
- 被 `@vue/cli-service` 发现；
|
||||
- 被其它开发者搜索到；
|
||||
- 通过 `vue add <name>` 或 `vue invoke <name>` 安装下来。
|
||||
|
||||
## 开发核心插件的注意事项
|
||||
|
||||
::: tip 注意
|
||||
这个章节只用于 `vuejs/vue-cli` 仓库内部的内建插件工作。
|
||||
:::
|
||||
|
||||
一个带有为本仓库注入额外依赖的 generator 的插件 (比如 `chai` 会通过 `@vue/cli-plugin-unit-mocha/generator/index.js` 被注入) 应该将这些依赖列入其自身的 `devDependencies` 字段。这会确保：
|
||||
|
||||
1. 这个包始终存在于该仓库的根 `node_modules` 中，因此我们不必在每次测试的时候重新安装它们。
|
||||
|
||||
2. `yarn.lock` 会保持其一致性，因此 CI 程序可以更好地利用缓存。
|
||||
|
||||
[creator-class]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli/lib/Creator.js
|
||||
[service-class]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-service/lib/Service.js
|
||||
[generator-api]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli/lib/GeneratorAPI.js
|
||||
[commands]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-service/lib/commands
|
||||
[config]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-service/lib/config
|
||||
[plugin-api]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-service/lib/PluginAPI.js
|
||||
[prompt-modules]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli/lib/promptModules
|
||||
[prompt-api]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli/lib/PromptModuleAPI.js
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,41 @@
|
||||
# UI 插件信息
|
||||
|
||||
你的插件在其 UI 中使用时，可以展示不同的附加信息，使其更容易被发现和辨认。
|
||||
|
||||
## Logo
|
||||
|
||||
你可以在将要发布到 npm 上的目录的根上放置一个 `logo.png`。它会展示在以下几个地方：
|
||||
- 搜索插件以安装时
|
||||
- 在已安装的插件列表中
|
||||
|
||||
|
||||
|
||||
这个 logo 应该是一个不透明的正方形图 (最好 84x84).
|
||||
|
||||
## 可发现性
|
||||
|
||||
为了提升你的插件在搜索时的可见度，请将描述插件的关键字放到插件的 `package.json` 文件的 `description` 字段。
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "vue-cli-plugin-apollo",
|
||||
"version": "0.7.7",
|
||||
"description": "vue-cli 3 plugin to add Apollo and GraphQL"
|
||||
}
|
||||
```
|
||||
|
||||
你应该将插件网站的 URL 或仓库添加添加到 `homepage` 或 `repository` 字段，这样“More Info”按钮就会在你的插件描述中展示出来。
|
||||
|
||||
```json
|
||||
{
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "git+https://github.com/Akryum/vue-cli-plugin-apollo.git"
|
||||
},
|
||||
"homepage": "https://github.com/Akryum/vue-cli-plugin-apollo#readme"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# UI 本地化
|
||||
|
||||
## 标准 UI
|
||||
|
||||
请遵循下列简单步骤来为 CLI UI 提交一种其它语言的翻译！
|
||||
|
||||
1. 运行 `navigator.languages` 或 `navigator.language` 为新的地区获取语言代码。*例如：`'fr'`。*
|
||||
|
||||
2. 搜索 npm 确认名为 `vue-cli-locale-<language code>` 的包是否已经存在。如果存在，则请通过 PR 为它贡献！如果没找到，则创建一个新的名为 `vue-cli-locale-<language code>` 的地区的包。*例如：`vue-cli-locale-fr`.*
|
||||
|
||||
3. 将地区的 JSON 文件放置在一个 `locales` 文件夹并将这个文件命名为语言代码。*例如：`locales/fr.json`。*
|
||||
|
||||
4. 在 `package.json` 文件中，设置 `unpkg` 字段为地区文件的路径。*例如：`"unpkg": "./locales/fr.json"`。*
|
||||
|
||||
5. 将包发布到 npm 上。
|
||||
|
||||
可以参考[这里](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-ui/locales)的英文地区文件。
|
||||
|
||||
作为示例，参考一份[法语的包](https://github.com/Akryum/vue-cli-locale-fr)。
|
||||
|
||||
## 翻译插件
|
||||
|
||||
你也可以在插件的根目录的 `locales` 文件夹放置与 [vue-i18n](https://github.com/kazupon/vue-i18n) 兼容的地区文件。这样做会在项目打开的时候自动加载，然后你可以使用 `$t` 在你的组件和 vue-i18n 辅助函数里翻译字符串。同样的 UI API (像 `describeTask`) 用到的字符串将会进入 vue-i18n，这样你就可以对它们做本地化。
|
||||
|
||||
示例 `locales` 文件夹：
|
||||
|
||||
```
|
||||
vue-cli-plugin/locales/en.json
|
||||
vue-cli-plugin/locales/fr.json
|
||||
```
|
||||
|
||||
API 的用法示例：
|
||||
|
||||
```js
|
||||
api.describeConfig({
|
||||
// vue-i18n 路径
|
||||
description: 'my-plugin.config.foo'
|
||||
})
|
||||
```
|
||||
|
||||
在组件中使用的示例：
|
||||
|
||||
```html
|
||||
<VueButton>{{ $t('my-plugin.actions.bar') }}</VueButton>
|
||||
```
|
||||
|
||||
如果你愿意的话，可以使用 `ClientAddonApi` 在一个客户端 addon 加载地区文件：
|
||||
|
||||
```js
|
||||
// 加载本地文件 (使用 vue-i18n)
|
||||
const locales = require.context('./locales', true, /[a-z0-9]+\.json$/i)
|
||||
locales.keys().forEach(key => {
|
||||
const locale = key.match(/([a-z0-9]+)\./i)[1]
|
||||
ClientAddonApi.addLocalization(locale, locales(key))
|
||||
})
|
||||
```
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
sidebarDepth: 0
|
||||
---
|
||||
|
||||
# 介绍
|
||||
|
||||
Vue CLI 是一个基于 Vue.js 进行快速开发的完整系统，提供：
|
||||
|
||||
- 通过 `@vue/cli` 搭建交互式的项目脚手架。
|
||||
- 通过 `@vue/cli` + `@vue/cli-service-global` 快速开始零配置原型开发。
|
||||
- 一个运行时依赖 (`@vue/cli-service`)，该依赖：
|
||||
- 可升级；
|
||||
- 基于 webpack 构建，并带有合理的默认配置；
|
||||
- 可以通过项目内的配置文件进行配置；
|
||||
- 可以通过插件进行扩展。
|
||||
- 一个丰富的官方插件集合，集成了前端生态中最好的工具。
|
||||
|
||||
Vue CLI 致力于将 Vue 生态中的工具基础标准化。它确保了各种构建工具能够基于智能的默认配置即可平稳衔接，这样你可以专注在撰写应用上，而不必花好几天去纠结配置的问题。与此同时，它也为每个工具提供了调整配置的灵活性，无需 eject。
|
||||
|
||||
## 该系统的组件
|
||||
|
||||
Vue CLI 有几个独立的部分——如果你看到了我们的[源代码](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue)，你会发现这个仓库里同时管理了多个单独发布的包。
|
||||
|
||||
### CLI
|
||||
|
||||
CLI (`@vue/cli`) 是一个全局安装的 npm 包，提供了终端里的 `vue` 命令。它可以通过 `vue create` 快速创建一个新项目的脚手架，或者直接通过 `vue serve` 构建新想法的原型。你也可以通过 `vue ui` 通过一套图形化界面管理你的所有项目。我们会在接下来的指南中逐章节深入介绍。
|
||||
|
||||
### CLI 服务
|
||||
|
||||
CLI 服务 (`@vue/cli-service`) 是一个开发环境依赖。它是一个 npm 包，局部安装在每个 `@vue/cli` 创建的项目中。
|
||||
|
||||
CLI 服务是构建于 [webpack](http://webpack.js.org/) 和 [webpack-dev-server](https://github.com/webpack/webpack-dev-server) 之上的。它包含了：
|
||||
|
||||
- 加载其它 CLI 插件的核心服务；
|
||||
- 一个针对绝大部分应用优化过的内部的 webpack 配置；
|
||||
- 项目内部的 `vue-cli-service` 命令，提供 `serve`、`build` 和 `inspect` 命令。
|
||||
|
||||
如果你熟悉 [create-react-app](https://github.com/facebookincubator/create-react-app) 的话，`@vue/cli-service` 实际上大致等价于 `react-scripts`，尽管功能集合不一样。
|
||||
|
||||
[CLI 服务](./cli-service.md)章节涵盖了它的具体用法。
|
||||
|
||||
### CLI 插件
|
||||
|
||||
CLI 插件是向你的 Vue 项目提供可选功能的 npm 包，例如 Babel/TypeScript 转译、ESLint 集成、单元测试和 end-to-end 测试等。Vue CLI 插件的名字以 `@vue/cli-plugin-` (内建插件) 或 `vue-cli-plugin-` (社区插件) 开头，非常容易使用。
|
||||
|
||||
当你在项目内部运行 `vue-cli-service` 命令时，它会自动解析并加载 `package.json` 中列出的所有 CLI 插件。
|
||||
|
||||
插件可以作为项目创建过程的一部分，或在后期加入到项目中。它们也可以被归成一组可复用的 preset。我们会在[插件和 preset](./plugins-and-presets.md) 章节进行深入讨论。
|
||||
@@ -0,0 +1,67 @@
|
||||
# 浏览器兼容性
|
||||
|
||||
## browserslist
|
||||
|
||||
你会发现 `package.json` 文件里有一个 `browserlist` 字段，指定里项目的目标浏览器的范围。这个值会被 [@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。
|
||||
|
||||
默认情况下，它会把 [`useBuiltIns: 'usage'`](https://new.babeljs.io/docs/en/next/babel-preset-env.html#usebuiltins-usage) 传递给 `@babel/preset-env`，这样它会根据源代码中出现的语言特性自动检测需要的 polyfill。这确保了最终包里 polyfill 数量的最小化。然而，这也意味着**如果其中一个依赖需要特殊的 polyfill，默认情况下 Babel 无法将其检测出来。**
|
||||
|
||||
如果有依赖需要 polyfill，你有几种选择：
|
||||
|
||||
1. **如果该依赖基于一个目标环境不支持的 ES 版本撰写：**将其添加到 `vue.config.js` 中的 [`transpileDependencies`](../config/#transpiledependencies) 选项。这会为该依赖同时开启语法语法转换和根据使用情况检测 polyfill。
|
||||
|
||||
2. **如果该依赖交付了 ES5 代码并显式地列出了需要的 polyfill：**你可以使用 `@vue/babel-preset-app` 的 [polyfills](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app#polyfills) 选项预包含所需要的 polyfill。**注意 `es6.promise` 将被默认包含，因为现在的库依赖 Promise 是非常普遍的。**
|
||||
|
||||
``` js
|
||||
// babel.config.js
|
||||
module.exports = {
|
||||
presets: [
|
||||
['@vue/app', {
|
||||
polyfills: [
|
||||
'es6.promise',
|
||||
'es6.symbol'
|
||||
]
|
||||
}]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
::: tip 提示
|
||||
我们推荐以这种方式添加 polyfill 而不是在源代码中直接导入它们，因为如果这里列出的 polyfill 在 `browserslist` 的目标中不需要，则它会被自动排除。
|
||||
:::
|
||||
|
||||
3. **如果该依赖交付 ES5 代码，但使用了 ES6+ 特性且没有显式地列出需要的 polyfill (例如 Vuetify)：**请使用 `useBuiltIns: 'entry'` 然后在入口文件添加 `import '@babel/polyfill'`。这会根据 `browserslist` 目标导入**所有** polyfill，这样你就不用再担心依赖的 polyfill 问题了，但是因为包含了一些没有用到的 polyfill 所以最终的包大小可能会增加。
|
||||
|
||||
更多细节可查阅 [@babel-preset/env 文档](https://new.babeljs.io/docs/en/next/babel-preset-env.html#usebuiltins-usage)。
|
||||
|
||||
## 现代模式
|
||||
|
||||
有了 Babel 我们可以兼顾所有最新的 ES2015+ 语言特性，但也意味着我们需要交付转译和 polyfill 后的包以支持旧浏览器。这些转译后的包通常都比原生的 ES2015+ 代码会更冗长，运行更慢。现如今绝大多数现代浏览器都已经支持了原生的 ES2015，所以因为要支持更老的浏览器而为它们交付笨重的代码是一种浪费。
|
||||
|
||||
Vue CLI 提供了一个“现代模式”帮你解决这个问题。以如下命令为生产环境构建：
|
||||
|
||||
``` bash
|
||||
vue-cli-service build --modern
|
||||
```
|
||||
|
||||
Vue CLI 会产生两个应用的版本：一个现代版的包，面向支持 [ES modules](https://jakearchibald.com/2017/es-modules-in-browsers/) 的现代浏览器，另一个旧版的包，面向不支持的旧浏览器。
|
||||
|
||||
最酷的是这里没有特殊的部署要求。其生成的 HTML 文件会自动使用 [Phillip Walton 精彩的博文](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/)中讨论到的技术：
|
||||
|
||||
- 现代版的包会通过 `<script type="module">` 在被支持的浏览器中加载；它们还会使用 `<link rel="modulepreload">` 进行预加载。
|
||||
|
||||
- 旧版的包会通过 `<script nomodule>` 加载，并会被支持 ES modules 的浏览器忽略。
|
||||
|
||||
- 一个针对 Safari 10 中 `<script nomodule>` 的修复会被自动注入。
|
||||
|
||||
对于一个 Hello World 应用来说，现代版的包已经小了 16%。在生产环境下，现代版的包通常都会表现出显著的解析速度和运算速度，从而改善应用的加载性能。
|
||||
|
||||
[autoprefixer]: https://github.com/postcss/autoprefixer
|
||||
[babel-preset-env]: https://new.babeljs.io/docs/en/next/babel-preset-env.html
|
||||
[browserslist]: https://github.com/ai/browserslist
|
||||
@@ -0,0 +1,130 @@
|
||||
# 构建目标
|
||||
|
||||
当你运行 `vue-cli-service build` 时，你可以通过 `--target` 选项指定不同的构建目标。它允许你将相同的源代码根据不同的用例生成不同的构建。
|
||||
|
||||
## 应用
|
||||
|
||||
应用模式是默认的模式。在这个模式中：
|
||||
|
||||
- `index.html` 会带有注入的资源和 resource hint
|
||||
- 第三方库会被分到一个独立包以便更好的缓存
|
||||
- 小于 10kb 的静态资源会被内联在 JavaScript 中
|
||||
- `public` 中的静态资源会被复制到输出目录中
|
||||
|
||||
## 库
|
||||
|
||||
::: tip 注意对 Vue 的依赖
|
||||
在库模式中，Vue 是*外置的*。这意味着包中不会有 Vue，即便你在代码中导入了 Vue。如果这个库会通过一个打包器使用，它将尝试通过打包器以依赖的方式加载 Vue；否则就会回退到一个全局的 `Vue` 变量。
|
||||
:::
|
||||
|
||||
你可以通过下面的命令将一个单独的入口构建为一个库：
|
||||
|
||||
```
|
||||
vue-cli-service build --target lib --name myLib [entry]
|
||||
```
|
||||
|
||||
```
|
||||
File Size Gzipped
|
||||
|
||||
dist/myLib.umd.min.js 13.28 kb 8.42 kb
|
||||
dist/myLib.umd.js 20.95 kb 10.22 kb
|
||||
dist/myLib.common.js 20.57 kb 10.09 kb
|
||||
dist/myLib.css 0.33 kb 0.23 kb
|
||||
```
|
||||
|
||||
这个入口可以是一个 `.js` 或一个 `.vue` 文件。如果没有指定入口，则会使用 `src/App.vue`。
|
||||
|
||||
构建一个库会输出：
|
||||
|
||||
- `dist/myLib.common.js`：一个给打包器用的 CommonJS 包 (不幸的是，webpack 目前还并没有支持 ES modules 输出格式的包)
|
||||
|
||||
- `dist/myLib.umd.js`：一个直接给浏览器或 AMD loader 使用的 UMD 包
|
||||
|
||||
- `dist/myLib.umd.min.js`：压缩后的 UMD 构建版本
|
||||
|
||||
- `dist/myLib.css`：提取出来的 CSS 文件 (可以通过在 `vue.config.js` 中设置 `css: { extract: false }` 强制内联)
|
||||
|
||||
### Vue vs. JS/TS 入口文件
|
||||
|
||||
当使用一个 `.vue` 文件作为入口时，你的库会直接暴露这个 Vue 组件本身，因为组件始终是默认导出的内容。
|
||||
|
||||
然而，当你使用一个 `.js` 或 `.ts` 文件作为入口时，它可能会包含具名导出，所以库会暴露为一个模块。也就是说你的库必须在 UMD 构建中通过 `window.yourLib.default` 访问，或在 CommonJS 构建中通过 `const myLib = require('mylib').default` 访问。如果你没有任何具名导出并希望直接暴露默认导出，你可以在 `vue.config.js` 中使用以下 webpack 配置：
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
configureWebpack: {
|
||||
output: {
|
||||
libraryExport: 'default'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Web Components 组件
|
||||
|
||||
::: tip 兼容性提示
|
||||
Web Components 模式不支持 IE11 及更低版本。[更多细节](https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-web-component-wrapper/README.md#兼容性)
|
||||
:::
|
||||
|
||||
::: tip 注意对 Vue 的依赖
|
||||
在 Web Components 模式中，Vue 是*外置的*。这意味着包中不会有 Vue，即便你在代码中导入了 Vue。这里的包会假设在页面中已经有一个可用的全局变量 `Vue`。
|
||||
:::
|
||||
|
||||
你可以通过下面的命令将一个单独的入口构建为一个库：
|
||||
|
||||
```
|
||||
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`。**
|
||||
|
||||
这个模式允许你的组件的使用者以一个普通 DOM 元素的方式使用这个 Vue 组件：
|
||||
|
||||
``` html
|
||||
<script src="https://unpkg.com/vue"></script>
|
||||
<script src="path/to/my-element.js"></script>
|
||||
|
||||
<!-- 可在普通 HTML 中或者其它任何框架中使用 -->
|
||||
<my-element></my-element>
|
||||
```
|
||||
|
||||
### 注册多个 Web Components 组件的包
|
||||
|
||||
当你构建一个 Web Components 组件包的时候，你也可以使用一个 glob 表达式作为入口指定多个组件目标：
|
||||
|
||||
```
|
||||
vue-cli-service build --target wc --name foo 'src/components/*.vue'
|
||||
```
|
||||
|
||||
当你构建多个 web component 时，`--name` 将会用于设置前缀，同时自定义元素的名称会由组件的文件名推导得出。比如一个名为 `HelloWorld.vue` 的组件携带 `--name foo` 将会生成的自定义元素名为 `<foo-hello-world>`。
|
||||
|
||||
### 异步 Web Components 组件
|
||||
|
||||
当指定多个 Web Components 组件作为目标时，这个包可能会变得非常大，并且用户可能只想使用你的包中注册的一部分组件。这时异步 Web Components 模式会生成一个 code-split 的包，带一个只提供所有组件共享的运行时，并预先注册所有的自定义组件小入口文件。一个组件真正的实现只会在页面中用到自定义元素相应的一个实例时按需获取：
|
||||
|
||||
```
|
||||
vue-cli-service build --target wc-async --name foo 'src/components/*.vue'
|
||||
```
|
||||
|
||||
```
|
||||
File Size Gzipped
|
||||
|
||||
dist/foo.0.min.js 12.80 kb 8.09 kb
|
||||
dist/foo.min.js 7.45 kb 3.17 kb
|
||||
dist/foo.1.min.js 2.91 kb 1.02 kb
|
||||
dist/foo.js 22.51 kb 6.67 kb
|
||||
dist/foo.0.js 17.27 kb 8.83 kb
|
||||
dist/foo.1.js 5.24 kb 1.64 kb
|
||||
```
|
||||
|
||||
现在用户在该页面上只需要引入 Vue 和这个入口文件即可：
|
||||
|
||||
``` html
|
||||
<script src="https://unpkg.com/vue"></script>
|
||||
<script src="path/to/foo.min.js"></script>
|
||||
|
||||
<!-- foo-one 的实现的 chunk 会在用到的时候自动获取 -->
|
||||
<foo-one></foo-one>
|
||||
```
|
||||
@@ -0,0 +1,131 @@
|
||||
# CLI 服务
|
||||
|
||||
## 使用命令
|
||||
|
||||
在一个 Vue CLI 项目中，`@vue/cli-service` 安装了一个名为 `vue-cli-service` 的命令。你可以在 npm scripts 中以 `vue-cli-service`、或者从终端中以 `./node_modules/.bin/vue-cli-service` 访问这个命令。
|
||||
|
||||
这是你使用默认 preset 的项目的 `package.json`：
|
||||
|
||||
``` json
|
||||
{
|
||||
"scripts": {
|
||||
"serve": "vue-cli-service serve",
|
||||
"build": "vue-cli-service build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
你可以通过 npm 或 Yarn 调用这些 script：
|
||||
|
||||
``` bash
|
||||
npm run serve
|
||||
# OR
|
||||
yarn serve
|
||||
```
|
||||
|
||||
如果你可以使用 [npx](https://github.com/zkat/npx) (最新版的 npm 应该已经自带)，也可以直接这样调用命令：
|
||||
|
||||
``` bash
|
||||
npx vue-cli-service serve
|
||||
```
|
||||
|
||||
## vue-cli-service serve
|
||||
|
||||
```
|
||||
用法：vue-cli-service serve [options]
|
||||
|
||||
选项：
|
||||
|
||||
--open 在服务器启动时打开浏览器
|
||||
--copy 在服务器启动时将 URL 复制到剪切版
|
||||
--mode 指定环境模式 (默认值：development)
|
||||
--host 指定 host (默认值：0.0.0.0)
|
||||
--port 指定 port (默认值：8080)
|
||||
--https 使用 https (默认值：false)
|
||||
```
|
||||
|
||||
`serve` 命令会启动一个开发服务器 (基于 [webpack-dev-server](https://github.com/webpack/webpack-dev-server)) 并附带开箱即用的模块热重载 (Hot-Module-Replacement)。
|
||||
|
||||
除了通过命令行参数，你也可以使用 `vue.config.js` 里的 [devServer](../config/#devserver) 字段配置开发服务器。
|
||||
|
||||
## vue-cli-service build
|
||||
|
||||
```
|
||||
用法：vue-cli-service build [options] [entry|pattern]
|
||||
|
||||
选项：
|
||||
|
||||
--mode 指定环境模式 (默认值：production)
|
||||
--dest 指定输出目录 (默认值：dist)
|
||||
--modern 面向现代浏览器不带自动回退地构建应用
|
||||
--target app | lib | wc | wc-async (默认值：app)
|
||||
--name 库或 Web Components 模式下的名字 (默认值：package.json 中的 "name" 字段或入口文件名)
|
||||
--no-clean 在构建项目之前不清除目标目录
|
||||
--report 生成 report.html 以帮助分析包内容
|
||||
--report-json 生成 report.json 以帮助分析包内容
|
||||
--watch 监听文件变化
|
||||
```
|
||||
|
||||
`vue-cli-service build` 会在 `dist/` 目录产生一个可用于生产环境的包，带有 JS/CSS/HTML 的压缩，和为更好的缓存而做的自动的 vendor chunk splitting。它的 chunk manifest 会内联在 HTML 里。
|
||||
|
||||
这里还有一些有用的命令参数：
|
||||
|
||||
- `--modern` 使用[现代模式](./browser-compatibility.md#现代模式)构建应用，为现代浏览器交付原生支持的 ES2015 代码，并生成一个兼容老浏览器的包用来自动回退。
|
||||
|
||||
- `--target` 允许你将项目中的任何组件以一个库或 Web Components 组件的方式进行构建。更多细节请查阅[构建目标](./build-targets.md)。
|
||||
|
||||
- `--report` 和 `--report-json` 会根据构建统计生成报告，它会帮助你分析包中包含的模块们的大小。
|
||||
|
||||
## vue-cli-service inspect
|
||||
|
||||
```
|
||||
用法：vue-cli-service inspect [options] [...paths]
|
||||
|
||||
选项：
|
||||
|
||||
--mode 指定环境模式 (默认值：development)
|
||||
```
|
||||
|
||||
你可以使用 `vue-cli-service inspect` 来审查一个 Vue CLI 项目的 webpack config。更多细节请查阅[审查 webpack config](./webpack.md#审查项目的-webpack-config)。
|
||||
|
||||
## 查看所有的可用命令
|
||||
|
||||
有些 CLI 插件会向 `vue-cli-service` 注入额外的命令。例如 `@vue/cli-plugin-eslint` 会注入 `vue-cli-service lint` 命令。你可以允许以下命令查看所有注入的命令：
|
||||
|
||||
``` bash
|
||||
npx vue-cli-service help
|
||||
```
|
||||
|
||||
你也可以这样学习每个命令可用的选项：
|
||||
|
||||
``` bash
|
||||
npx vue-cli-service help [command]
|
||||
```
|
||||
|
||||
## 缓存和并行处理
|
||||
|
||||
- `cache-loader` 会默认为 Vue/Babel/TypeScript 编译开启。文件会缓存在 `node_modules/.cache` 中——如果你遇到了编译方面的问题，记得先删掉缓存目录之后再试试看。
|
||||
|
||||
- `thread-loader` 会在多核 CPU 的机器上为 Babel/TypeScript 转译开启。
|
||||
|
||||
## Git Hook
|
||||
|
||||
在安装之后，`@vue/cli-service` 也会安装 [yorkie](https://github.com/yyx990803/yorkie)，它会让你在 `package.json` 的 `gitHooks` 字段中方便地指定 Git hook：
|
||||
|
||||
``` json
|
||||
{
|
||||
"gitHooks": {
|
||||
"pre-commit": "lint-staged"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: warning
|
||||
`yorkie` fork 自 [`husky`](https://github.com/typicode/husky) 且并不和之后的版本兼容。
|
||||
:::
|
||||
|
||||
## 配置时无需 Eject
|
||||
|
||||
通过 `vue create` 创建的项目无需额外的配置就已经可以跑起来了。插件的设计也是可以相互共存的，所以绝大多数情况下，你只需要在交互式命令提示中选取需要的功能即可。
|
||||
|
||||
不过我们也知道满足每一个需求是不太可能的，而且一个项目的需求也会不断改变。通过 Vue CLI 创建的项目让你无需 eject 就能够配置工具的几乎每个角落。更多细节请查阅[配置参考](../config/)。
|
||||
@@ -0,0 +1,87 @@
|
||||
# 创建一个项目
|
||||
|
||||
## 安装
|
||||
|
||||
::: 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
|
||||
|
||||
运行以下命令来创建一个新项目：
|
||||
|
||||
``` bash
|
||||
vue create hello-world
|
||||
```
|
||||
|
||||
你会被提示选取一个 preset。你可以选默认的包含了基本的 Babel + ESLint 设置的 preset，也可以选“手动选择特性”来选取需要的特性。
|
||||
|
||||
|
||||
|
||||
这个默认的设置非常适合快速创建一个新项目的原型，而手动设置则提供了更多的选项，它们是面向生产的项目更加需要的。
|
||||
|
||||
|
||||
|
||||
如果你决定手动选择特性，在操作提示的最后你可以选择将已选项保存为一个将来可复用的 preset。我们会在下一个章节讨论 preset 和插件。
|
||||
|
||||
::: tip ~/.vuerc
|
||||
被保存的 preset 将会存在用户的 home 目录下一个名为 `.vuerc` 的 JSON 文件里。如果你想要修改被保存的 preset / 选项，可以编辑这个文件。
|
||||
|
||||
在项目创建的过程中，你也会被提示选择喜欢的包管理器或使用[淘宝 npm 镜像源](https://npm.taobao.org/)以更快地安装依赖。这些选择也将会存入 `~/.vuerc`。
|
||||
:::
|
||||
|
||||
`vue create` 命令有一些可选项，你可以通过运行以下命令进行探索：
|
||||
|
||||
``` bash
|
||||
vue create --help
|
||||
```
|
||||
|
||||
```
|
||||
用法：create [options] <app-name>
|
||||
|
||||
创建一个由 `vue-cli-service` 提供支持的新项目
|
||||
|
||||
|
||||
选项：
|
||||
|
||||
-p, --preset <presetName> 忽略提示符并使用已保存的或远程的预设选项
|
||||
-d, --default 忽略提示符并使用默认预设选项
|
||||
-i, --inlinePreset <json> 忽略提示符并使用内联的 JSON 字符串预设选项
|
||||
-m, --packageManager <command> 在安装依赖时使用指定的 npm 客户端
|
||||
-r, --registry <url> 在安装依赖时使用指定的 npm registry (仅用于 npm 客户端)
|
||||
-g, --git [message] 强制 / 跳过 git 初始化，并可选的指定初始化提交信息
|
||||
-f, --force 覆写目标目录可能存在的配置
|
||||
-c, --clone 使用 git clone 获取远程预设选项
|
||||
-x, --proxy 使用指定的代理创建项目
|
||||
-h, --help 输出使用帮助信息
|
||||
```
|
||||
|
||||
## 使用图形化界面
|
||||
|
||||
你也可以通过 `vue ui` 命令以图形化界面创建和管理项目：
|
||||
|
||||
``` bash
|
||||
vue ui
|
||||
```
|
||||
|
||||
上述命令会打开一个浏览器窗口，并以图形化界面将你引导至项目创建的流程。
|
||||
|
||||
|
||||
|
||||
## 拉取 2.x 模板 (旧版本)
|
||||
|
||||
Vue CLI 3 和旧版使用了相同的 `vue` 命令，所以 Vue CLI 2 (`vue-cli`) 被覆盖了。如果你仍然需要使用旧版本的 `vue init` 功能，你可以全局安装一个桥接工具：
|
||||
|
||||
``` bash
|
||||
npm install -g @vue/cli-init
|
||||
# `vue init` 的运行效果将会跟 `vue-cli@2.x` 相同
|
||||
vue init webpack my-project
|
||||
```
|
||||
@@ -0,0 +1,111 @@
|
||||
# 配合 CSS
|
||||
|
||||
Vue CLI 项目天生支持 [PostCSS](http://postcss.org/)、[CSS Modules](https://github.com/css-modules/css-modules) 和包含 [Sass](https://sass-lang.com/)、[Less](http://lesscss.org/)、[Stylus](http://stylus-lang.com/) 在内的预处理器。
|
||||
|
||||
## 预处理器
|
||||
|
||||
你可以在创建项目的时候选择预处理器 (Sass/Less/Stylus)。如果当时没有选好，内置的 webpack 仍然会被预配置为可以完成所有的处理。你也可以手动安装相应的 webpack loader：
|
||||
|
||||
``` bash
|
||||
# Sass
|
||||
npm install -D sass-loader node-sass
|
||||
|
||||
# Less
|
||||
npm install -D less-loader less
|
||||
|
||||
# Stylus
|
||||
npm install -D stylus-loader stylus
|
||||
```
|
||||
|
||||
然后你就可以导入相应的文件类型，或在 `*.vue` 文件中这样来使用：
|
||||
|
||||
``` vue
|
||||
<style lang="scss">
|
||||
$color = red;
|
||||
</style>
|
||||
```
|
||||
|
||||
## PostCSS
|
||||
|
||||
Vue CLI 内部使用了 PostCSS。
|
||||
|
||||
你可以通过 `.postcssrc` 或任何 [postcss-load-config](https://github.com/michael-ciniawsky/postcss-load-config) 支持的配置源来配置 PostCSS。也可以通过 `vue.config.js` 中的 `css.loaderOptions.postcss` 配置 [postcss-loader](https://github.com/postcss/postcss-loader)。
|
||||
|
||||
我们默认开启了 [autoprefixer](https://github.com/postcss/autoprefixer)。如果要配置目标浏览器，可使用 `package.json` 的 [browserslist](../guide/browser-compatibility.html#browserslist) 字段。
|
||||
|
||||
::: tip 关于 CSS 中浏览器前缀规则的注意事项
|
||||
在生产环境构建中，Vue CLI 会优化 CSS 并基于目标浏览器抛弃不必要的浏览器前缀规则。因为默认开启了 `autoprefixer`，你只使用无前缀的 CSS 规则即可。
|
||||
:::
|
||||
|
||||
## CSS Modules
|
||||
|
||||
你可以通过 `<style module>` 以开箱即用的方式[在 `*.vue` 文件中使用 CSS Modules](https://vue-loader.vuejs.org/zh/guide/css-modules.html)。
|
||||
|
||||
如果想在 JavaScript 中作为 CSS Modules 导入 CSS 或其它预处理文件，该文件应该以 `.module.(css|less|sass|scss|styl)` 结尾：
|
||||
|
||||
``` js
|
||||
import styles from './foo.module.css'
|
||||
// 所有支持的预处理器都一样工作
|
||||
import sassStyles from './foo.module.scss'
|
||||
```
|
||||
|
||||
如果你想去掉文件名中的 `.module`，可以设置 `vue.config.js` 中的 `css.modules` 为 `true`：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
css: {
|
||||
modules: true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你希望自定义生成的 CSS Modules 模块的类名，可以通过 `vue.config.js` 中的 `css.loaderOptions.css` 选项来实现。所有的 `css-loader` 选项在这里都是支持的，例如 `localIdentName` 和 `camelCase`：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
css: {
|
||||
loaderOptions: {
|
||||
css: {
|
||||
localIdentName: '[name]-[hash]',
|
||||
camelCase: 'only'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 向预处理器 Loader 传递选项
|
||||
|
||||
有的时候你想要向 webpack 的预处理器 loader 传递选项。你可以使用 `vue.config.js` 中的 `css.loaderOptions` 选项。比如你可以这样向所有 Sass 样式传入共享的全局变量：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
const fs = require('fs')
|
||||
|
||||
module.exports = {
|
||||
css: {
|
||||
loaderOptions: {
|
||||
// 给 sass-loader 传递选项
|
||||
sass: {
|
||||
// @/ 是 src/ 的别名
|
||||
// 所以这里假设你有 `src/variables.scss` 这个文件
|
||||
data: `@import "@/variables.scss";`
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Loader 可以通过 `loaderOptions` 配置，包括：
|
||||
|
||||
- [css-loader](https://github.com/webpack-contrib/css-loader)
|
||||
- [postcss-loader](https://github.com/postcss/postcss-loader)
|
||||
- [sass-loader](https://github.com/webpack-contrib/sass-loader)
|
||||
- [less-loader](https://github.com/webpack-contrib/less-loader)
|
||||
- [stylus-loader](https://github.com/shama/stylus-loader)
|
||||
|
||||
::: tip 提示
|
||||
这样做比使用 `chainWebpack` 手动指定 loader 更推荐，因为这些选项需要应用在使用了相应 loader 的多个地方。
|
||||
:::
|
||||
@@ -0,0 +1,111 @@
|
||||
# 部署
|
||||
|
||||
## 通用指南
|
||||
|
||||
如果你用 Vue CLI 处理静态资源并和后端框架一起作为部署的一部分，那么你需要的仅仅是确保 Vue CLI 生成的构建文件在正确的位置，并遵循后端框架的发布方式即可。
|
||||
|
||||
如果你独立于后端部署前端应用——也就是说后端暴露一个前端可访问的 API，然后前端实际上是纯静态应用。那么你可以将 `dist` 目录里构建的内容部署到任何静态文件服务器中，但要确保正确的 [baseUrl](../config/#baseurl)。
|
||||
|
||||
### 本地预览
|
||||
|
||||
`dist` 目录需要启动一个 HTTP 服务器来访问，所以以 `file://` 协议直接打开 `dist/index.html` 是不会工作的。在本地预览生产环境构建最简单的方式就是使用一个 Node.js 静态文件服务器，例如 [serve](https://github.com/zeit/serve)：
|
||||
|
||||
``` bash
|
||||
npm install -g serve
|
||||
# -s 参数的意思是将其架设在 Single-Page Application 模式下
|
||||
# 这个模式会处理即将提到的路由问题
|
||||
serve -s dist
|
||||
```
|
||||
|
||||
### 使用 `history.pushState` 的路由
|
||||
|
||||
如果你在 `history` 模式下使用 Vue Router，是无法搭配简单的静态文件服务器的。例如，如果你使用 Vue Router 为 `/todos/42/` 定义了一个路由，开发服务器已经配置了相应的 `localhost:3000/todos/42` 相应，但是一个为生产环境构建架设的简单的静态服务器会却会返回 404。
|
||||
|
||||
为了解决这个问题，你需要配置生产环境服务器，将任何没有匹配到静态文件的请求回退到 `index.html`。Vue Router 的文档提供了[常用服务器配置指引](https://router.vuejs.org/zh/guide/essentials/history-mode.html)。
|
||||
|
||||
### CORS
|
||||
|
||||
如果前端静态内容是部署在与后端 API 不同的域名上，你需要适当地配置 [CORS](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Access_control_CORS)。
|
||||
|
||||
### PWA
|
||||
|
||||
如果你使用了 PWA 插件，那么应用必须架设在 HTTPS 上，这样 [Service Worker](https://developer.mozilla.org/zh-CN/docs/Web/API/Service_Worker_API) 才能被正确注册。
|
||||
|
||||
## Platform Guides
|
||||
|
||||
### GitHub Pages
|
||||
|
||||
> TODO | Open to contribution.
|
||||
|
||||
### GitLab Pages
|
||||
|
||||
As described by [GitLab Pages documentation](https://docs.gitlab.com/ee/user/project/pages/), everything happens with a `.gitlab-ci.yml` file placed in the root of your repository. This working example will get you started:
|
||||
|
||||
```yaml
|
||||
# .gitlab-ci.yml file to be placed in the root of your repository
|
||||
|
||||
pages: # the job must be named pages
|
||||
image: node:latest
|
||||
stage: deploy
|
||||
script:
|
||||
- npm ci
|
||||
- npm run build
|
||||
- mv public public-vue # GitLab Pages hooks on the public folder
|
||||
- mv dist public # rename the dist folder (result of npm run build)
|
||||
artifacts:
|
||||
paths:
|
||||
- public # artifact path must be /public for GitLab Pages to pick it up
|
||||
only:
|
||||
- master
|
||||
```
|
||||
|
||||
Typically, your static website will be hosted on https://yourUserName.gitlab.io/yourProjectName, so you will also want to create an initial `vue.config.js` file to [update the `BASE_URL`](https://github.com/vuejs/vue-cli/tree/dev/docs/config#baseurl) value to match:
|
||||
|
||||
```javascript
|
||||
// vue.config.js file to be place in the root of your repository
|
||||
// make sure you update `yourProjectName` with the name of your GitLab project
|
||||
|
||||
module.exports = {
|
||||
baseUrl: process.env.NODE_ENV === 'production'
|
||||
? '/yourProjectName/'
|
||||
: '/'
|
||||
}
|
||||
```
|
||||
|
||||
Please read through the docs on [GitLab Pages domains](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_one.html#gitlab-pages-domain) for more info about the URL where your project website will be hosted. Be aware you can also [use a custom domain](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html#adding-your-custom-domain-to-gitlab-pages).
|
||||
|
||||
Commit both the `.gitlab-ci.yml` and `vue.config.js` files before pushing to your repository. A GitLab CI pipeline will be triggered: when successful, visit your project's `Settings > Pages` to see your website link, and click on it.
|
||||
|
||||
### Netlify
|
||||
|
||||
> TODO | Open to contribution.
|
||||
|
||||
Also checkout [vue-cli-plugin-netlify-lambda](https://github.com/netlify/vue-cli-plugin-netlify-lambda).
|
||||
|
||||
### Amazon S3
|
||||
|
||||
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.
|
||||
|
||||
### Now
|
||||
|
||||
> TODO | Open to contribution.
|
||||
|
||||
### Stdlib
|
||||
|
||||
> TODO | Open to contribution.
|
||||
|
||||
### Heroku
|
||||
|
||||
> TODO | Open to contribution.
|
||||
|
||||
### Surge
|
||||
|
||||
> TODO | Open to contribution.
|
||||
@@ -0,0 +1,148 @@
|
||||
# HTML 和静态资源
|
||||
|
||||
## HTML
|
||||
|
||||
### Index 文件
|
||||
|
||||
`public/index.html` 文件是一个会被 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 处理的模板。在构建过程中，资源链接会被自动注入。另外，Vue CLI 也会自动注入 resource hint (`preload/prefetch`、manifest 和图标链接 (当用到 PWA 插件时) 以及构建过程中处理的 JavaScript 和 CSS 文件的资源链接。
|
||||
|
||||
### 插值
|
||||
|
||||
因为 index 文件被用作模板，所以你可以使用 [lodash template](https://lodash.com/docs/4.17.10#template) 语法插入内容：
|
||||
|
||||
- `<%= VALUE %>` 用来做不转义插值；
|
||||
- `<%- VALUE %>` 用来做 HTML 转义插值；
|
||||
- `<% expression %>` 用来描述 JavaScript 流程控制。
|
||||
|
||||
除了[被 `html-webpack-plugin` 暴露的默认值](https://github.com/jantimon/html-webpack-plugin#writing-your-own-templates)之外，所有[客户端环境变量](./mode-and-env.md#using-env-variables-in-client-side-code)也可以直接使用。例如，`BASE_URL` 的用法：
|
||||
|
||||
``` html
|
||||
<link rel="icon" href="<%= BASE_URL %>favicon.ico">
|
||||
```
|
||||
|
||||
更多内容可以查阅：
|
||||
- [baseUrl](../config/#baseurl)
|
||||
|
||||
### Preload
|
||||
|
||||
[`<link rel="preload">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Preloading_content) 是一种 resource hint，用来指定页面加载后很快会被用到的资源，所以在页面加载的过程中，我们希望在浏览器开始主体渲染之前尽早 preload。
|
||||
|
||||
默认情况下，一个 Vue CLI 应用会为所有初始化渲染需要的文件自动生成 preload 提示。
|
||||
|
||||
这些提示会被 [@vue/preload-webpack-plugin](https://github.com/vuejs/preload-webpack-plugin) 注入，并且可以通过 `chainWebpack` 的 `config.plugin('preload')` 进行修改和删除。
|
||||
|
||||
### Prefetch
|
||||
|
||||
[`<link rel="prefetch">`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Link_prefetching_FAQ) 是一种 resource hint，用来告诉浏览器在页面加载完成后，利用空闲时间提前获取用户未来可能会访问的内容。
|
||||
|
||||
默认情况下，一个 Vue CLI 应用会为所有作为 async chunk 生成的 JavaScript 文件 ([通过动态 `import()` 按需 code splitting](https://webpack.js.org/guides/code-splitting/#dynamic-imports) 的产物) 自动生成 prefetch 提示。
|
||||
|
||||
这些提示会被 [@vue/preload-webpack-plugin](https://github.com/vuejs/preload-webpack-plugin) 注入，并且可以通过 `chainWebpack` 的 `config.plugin('prefetch')` 进行修改和删除。
|
||||
|
||||
示例：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
// 移除 prefetch 插件
|
||||
config.plugins.delete('prefetch')
|
||||
|
||||
// 或者
|
||||
// 修改它的选项：
|
||||
config.plugin('prefetch').tap(options => {
|
||||
options.fileBlackList.push([/myasyncRoute(.)+?\.js$/])
|
||||
return options
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: tip 提示
|
||||
Prefetch 链接将会消耗带宽。如果你的应用很大且有很多 async chunk，而用户主要使用的是对带宽较敏感的移动端，那么你可能需要关掉 prefetch 链接。
|
||||
:::
|
||||
|
||||
### 构建一个多页应用
|
||||
|
||||
不是每个应用都需要是一个单页应用。Vue CLI 支持使用 [`vue.config.js` 中的 `pages` 选项](../config/#pages)构建一个多页面的应用。构建好的应用将会在不同的入口之间高效共享通用的 chunk 以获得最佳的加载性能。
|
||||
|
||||
## 处理静态资源
|
||||
|
||||
静态资源可以通过两种方式进行处理：
|
||||
|
||||
- 在 JavaScript 被导入或在 template/CSS 中通过相对路径被引用。这类引用会被 webpack 处理。
|
||||
|
||||
- 放置在 `public` 目录下或通过绝对路径被引用。这类资源将会直接被拷贝，而不会经过 webpack 的处理。
|
||||
|
||||
### 从相对路径导入
|
||||
|
||||
当你在 JavaScript、CSS 或 `*.vue` 文件中使用相对路径 (必须以 `.` 开头) 引用一个静态资源时，该资源将会被包含进入 webpack 的依赖图中。在其编译过程中，所有诸如 `<img src="...">`、`background: url(...)` 和 CSS `@import` 的资源 URL **都会被解析为一个模块依赖**。
|
||||
|
||||
For example, `url(./image.png)` will be translated into `require('./image.png')`, and
|
||||
例如，`url(./image.png)` 会被翻译为 `require('./image.png')`，而：
|
||||
|
||||
``` html
|
||||
<img src="./image.png">
|
||||
```
|
||||
|
||||
将会被编译到：
|
||||
|
||||
``` js
|
||||
h('img', { attrs: { src: require('./image.png') }})
|
||||
```
|
||||
|
||||
在其内部，我们通过 `file-loader` 用版本哈希值和正确的公共基础路径来决定最终的文件路径，再用 `url-loader` 将小于 10kb 的资源内联，以减少 HTTP 请求的数量。
|
||||
|
||||
### URL 转换规则
|
||||
|
||||
- 如果 URL 是一个绝对路径 (例如 `/images/foo.png`)，它将会被保留不变。
|
||||
|
||||
- 如果 URL 以 `.` 开头，它会作为一个相对模块请求被解释且基于你的文件系统中的目录结构进行解析。
|
||||
|
||||
- 如果 URL 以 `~` 开头，其后的任何内容都会作为一个模块请求被解析。这意味着你甚至可以引用 Node 模块中的资源：
|
||||
|
||||
``` html
|
||||
<img src="~/some-npm-package/foo.png">
|
||||
```
|
||||
|
||||
- 如果 URL 以 `@` 开头，它也会作为一个模块请求被解析。它的用处在于 Vue CLI 默认会设置一个指向 `<projectRoot>/src` 的别名 `@`。
|
||||
|
||||
### `public` 文件夹
|
||||
|
||||
任何放置在 `public` 文件夹的静态资源都会被简单的复制，而不经过 webpack。你需要通过绝对路径来引用它们。
|
||||
|
||||
注意我们推荐将资源作为你的模块依赖图的一部分导入，这样它们会通过 webpack 的处理并获得如下好处：
|
||||
|
||||
- 脚本和样式表会被压缩且打包在一起，从而避免额外的网络请求。
|
||||
- 文件丢失会直接在编译时报错，而不是到了用户端才产生 404 错误。
|
||||
- 最终生成的文件名包含了内容哈希，因此你不必担心浏览器会缓存它们的老版本。
|
||||
|
||||
`public` 目录提供的是一个**应急手段**，当你通过绝对路径引用它时，留意应用将会部署到哪里。如果你的应用没有部署在域名的根部，那么你需要为你的 URL 配置 [baseUrl](../config/#baseurl) 前缀：
|
||||
|
||||
- 在 `public/index.html` 或其它通过 `html-webpack-plugin` 用作模板的 HTML 文件中，你需要通过 `<%= BASE_URL %>` 设置链接前缀：
|
||||
|
||||
``` html
|
||||
<link rel="icon" href="<%= BASE_URL %>favicon.ico">
|
||||
```
|
||||
|
||||
- 在模板中，你首先需要向你的组件传入基础 URL：
|
||||
|
||||
``` js
|
||||
data () {
|
||||
return {
|
||||
baseUrl: process.env.BASE_URL
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后：
|
||||
|
||||
``` html
|
||||
<img :src="`${baseUrl}my-image.png`">
|
||||
```
|
||||
|
||||
### 何时使用 `public` 文件夹
|
||||
|
||||
- 你需要在构建输出中指定一个文件的名字。
|
||||
- 你有上千个图片，需要动态引用它们的路径。
|
||||
- 有些库可能和 webpack 不兼容，这时你除了将其用一个独立的 `<script>` 标签引入没有别的选择。
|
||||
@@ -0,0 +1,81 @@
|
||||
# 环境变量和模式
|
||||
|
||||
你可以替换你的项目根目录中的下列文件来指定环境变量：
|
||||
|
||||
``` bash
|
||||
.env # 在所有的环境中被载入
|
||||
.env.local # 在所有的环境中被载入，但会被 git 忽略
|
||||
.env.[mode] # 只在指定的模式中被载入
|
||||
.env.[mode].local # 只在指定的模式中被载入，但会被 git 忽略
|
||||
```
|
||||
|
||||
一个环境文件只包含环境变量的“键=值”对：
|
||||
|
||||
```
|
||||
FOO=bar
|
||||
VUE_APP_SECRET=secret
|
||||
```
|
||||
|
||||
被载入的变量将会对 `vue-cli-service` 的所有命令、插件和依赖可用。
|
||||
|
||||
## 模式
|
||||
|
||||
**模式**是 Vue CLI 项目中一个重要的概念。默认情况下，一个 Vue CLI 项目有三个模式：
|
||||
|
||||
- `development` 模式用于 `vue-cli-service serve`
|
||||
- `production` 模式用于 `vue-cli-service build` 和 `vue-cli-service test:e2e`
|
||||
- `test` 模式用于 `vue-cli-service test:unit`
|
||||
|
||||
注意模式不同于 `NODE_ENV`，一个模式可以包含多个环境变量。也就是说，每个模式都会将 `NODE_ENV` 的值设置为模式的名称——比如在 development 模式下 `NODE_ENV` 的值会被设置为 `"development"`。
|
||||
|
||||
你可以通过为 `.env` 文件增加后缀来设置某个模式下特有的环境变量。比如，如果你在项目根目录创建一个名为 `.env.development` 的文件，那么在这个文件里声明过的变量就只会在 development 模式下被载入。
|
||||
|
||||
你可以通过传递 `--mode` 选项参数为命令行覆写默认的模式。例如，如果你想要在构建命令中使用开发环境变量，请在你的 `package.json` 脚本中加入：
|
||||
|
||||
```
|
||||
"dev-build": "vue-cli-service build --mode development",
|
||||
```
|
||||
|
||||
## 示例：Staging 模式
|
||||
|
||||
假设我们有一个应用包含以下 `.env` 文件：
|
||||
|
||||
```
|
||||
VUE_APP_TITLE=My App
|
||||
```
|
||||
|
||||
和 `.env.staging` 文件：
|
||||
|
||||
```
|
||||
NODE_ENV=production
|
||||
VUE_APP_TITLE=My App (staging)
|
||||
```
|
||||
|
||||
- `vue-cli-service build` 会加载可能存在的 `.env`、`.env.production` 和 `.env.production.local` 文件然后构建出生产环境应用；
|
||||
|
||||
- `vue-cli-service build --mode staging` 会在 staging 模式下加载可能存在的 `.env`、`.env.staging` 和 `.env.staging.local` 文件然后构建出生产环境应用。
|
||||
|
||||
这两种情况下，根据 `NODE_ENV`，构建出的应用都是生产环境应用，但是在 staging 版本中，`process.env.VUE_APP_TITLE` 被覆写成了另一个值。
|
||||
|
||||
## 在客户端侧代码中使用环境变量
|
||||
|
||||
只有以 `VUE_APP_` 开头的变量会被 `webpack.DefinePlugin` 静态嵌入到客户端侧的包中。你可以在应用的代码中这样访问它们：
|
||||
|
||||
``` js
|
||||
console.log(process.env.VUE_APP_SECRET)
|
||||
```
|
||||
|
||||
在构建过程中，`process.env.VUE_APP_SECRET` 将会被相应的值所取代。在 `VUE_APP_SECRET=secret` 的情况下，它会被替换为 `"sercet"`。
|
||||
|
||||
除了 `VUE_APP_*` 变量之外，在你的应用代码中始终可用的还有两个特殊的变量：
|
||||
|
||||
- `NODE_ENV` - 会是 `"development"`、`"production"` 或 `"test"` 中的一个。具体的值取决于应用运行的[模式](#模式)。
|
||||
- `BASE_URL` - 会和 `vue.config.js` 中的 `baseUrl` 选项相符，即你的应用会部署到的基础路径。
|
||||
|
||||
所有解析出来的环境变量都可以在 `public/index.html` 中以 [HTML 插值](./html-and-static-assets.md#插值)中介绍的方式使用。
|
||||
|
||||
## 只在本地有效的变量
|
||||
|
||||
有的时候你可能有一些不应该提交到代码仓库中的变量，尤其是当你的项目托管在公共仓库时。这种情况下你应该使用一个 `.env.local` 文件取而代之。本地环境文件默认会被忽略，且出现在 `.gitignore` 中。
|
||||
|
||||
`.local` 也可以加在指定模式的环境文件上，比如 `.env.development.local` 将会在 development 模式下被载入，且被 git 忽略。
|
||||
@@ -0,0 +1,159 @@
|
||||
# 插件和 Preset
|
||||
|
||||
## 插件
|
||||
|
||||
Vue CLI 使用了一套基于插件的架构。如果你查阅一个新创建项目的 `package.json`，就会发现依赖都是以 `@vue/cli-plugin-` 开头的。插件可以修改 webpack 的内部配置，也可以向 `vue-cli-service` 注入命令。在项目创建的过程中，绝大部分列出的特性都是通过插件来实现的。
|
||||
|
||||
基于插件的架构使得 Vue CLI 灵活且可扩展。如果你对开发一个插件感兴趣，请翻阅[插件开发指南](../dev-guide/plugin-dev.md)。
|
||||
|
||||
### 在现有的项目中安装插件
|
||||
|
||||
每个 CLI 插件都会包含一个 (用来创建文件的) 生成器和一个 (用来调整 webpack 核心配置和注入命令的) 运行时插件。当你使用 `vue create` 来创建一个新项目的时候，有些插件会根据你选择的特性被预安装好。如果你想在一个已经被创建好的项目中安装一个插件，可以使用 `vue add` 命令：
|
||||
|
||||
``` bash
|
||||
vue add @vue/eslint
|
||||
```
|
||||
|
||||
::: tip 提示
|
||||
`vue add` 的设计意图是为了安装和调用 Vue CLI 插件。这不意味着替换掉普通的 npm 包。对于这些普通的 npm 包，你仍然需要选用包管理器。
|
||||
:::
|
||||
|
||||
::: warning 警告
|
||||
我们推荐在运行 `vue add` 之前将项目的最新状态提交，因为该命令可能调用插件的文件生成器并很有可能更改你现有的文件。
|
||||
:::
|
||||
|
||||
这个命令将 `@vue/eslint` 解析为完整的包名 `@vue/cli-plugin-eslint`，然后从 npm 安装它，调用它的生成器。
|
||||
|
||||
``` bash
|
||||
# 这个和之前的用法等价
|
||||
vue add @vue/cli-plugin-eslint
|
||||
```
|
||||
|
||||
如果不带 `@vue` 前缀，该命令会换作解析一个 unscoped 的包。例如以下命令会安装第三方插件 `vue-cli-plugin-apollo`：
|
||||
|
||||
``` bash
|
||||
# 安装并调用 vue-cli-plugin-apollo
|
||||
vue add apollo
|
||||
```
|
||||
|
||||
你也可以基于一个指定的 scope 使用第三方插件。例如如果一个插件名为 `@foo/vue-cli-plugin-bar`，你可以这样添加它：
|
||||
|
||||
``` bash
|
||||
vue add @foo/bar
|
||||
```
|
||||
|
||||
你可以向被安装的插件传递生成器选项 (这样做会跳过命令提示)：
|
||||
|
||||
``` bash
|
||||
vue add @vue/eslint --config airbnb --lintOn save
|
||||
```
|
||||
|
||||
`vue-router` 和 `vuex` 的情况比较特殊——它们并没有自己的插件，但是你仍然可以这样添加它们：
|
||||
|
||||
``` bash
|
||||
vue add router
|
||||
vue add vuex
|
||||
```
|
||||
|
||||
如果一个插件已经被安装，你可以使用 `vue invoke` 命令跳过安装过程，只调用它的生成器。这个命令会接受和 `vue add` 相同的参数。
|
||||
|
||||
## Preset
|
||||
|
||||
一个 Vue CLI preset 是一个包含创建新项目所需预定义选项和插件的 JSON 对象，让用户无需在命令提示中选择它们。
|
||||
|
||||
在 `vue create` 过程中保存的 preset 会被放在你的 home 目录下的一个配置文件中 (`~/.vuerc`)。你可以通过直接编辑这个文件来调整、添加、删除保存好的 preset。
|
||||
|
||||
这里有一个 preset 的示例：
|
||||
|
||||
``` json
|
||||
{
|
||||
"useConfigFiles": true,
|
||||
"router": true,
|
||||
"vuex": true,
|
||||
"cssPreprocessor": "sass",
|
||||
"plugins": {
|
||||
"@vue/cli-plugin-babel": {},
|
||||
"@vue/cli-plugin-eslint": {
|
||||
"config": "airbnb",
|
||||
"lintOn": ["save", "commit"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Preset 的数据会被插件生成器用来生成相应的项目文件。除了上述这些字段，你也可以为集成工具添加配置：
|
||||
|
||||
``` json
|
||||
{
|
||||
"useConfigFiles": true,
|
||||
"plugins": {...},
|
||||
"configs": {
|
||||
"vue": {...},
|
||||
"postcss": {...},
|
||||
"eslintConfig": {...},
|
||||
"jest": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这些额外的配置将会根据 `useConfigFiles` 的值被合并到 `package.json` 或相应的配置文件中。例如，当 `"useConfigFiles": true` 的时候，`configs` 的值将会被合并到 `vue.config.js` 中。
|
||||
|
||||
### Preset 插件的版本管理
|
||||
|
||||
你可以显式地指定用到的插件的版本：
|
||||
|
||||
``` json
|
||||
{
|
||||
"plugins": {
|
||||
"@vue/cli-plugin-eslint": {
|
||||
"version": "^3.0.0",
|
||||
// ... 该插件的其它选项
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
注意对于官方插件来说这不是必须的——当被忽略时，CLI 会自动使用 registry 中最新的版本。不过**我们推荐为 preset 列出的所有第三方插件提供显式的版本范围**。
|
||||
|
||||
### 允许插件的命令提示
|
||||
|
||||
每个插件在项目创建的过程中都可以注入它自己的命令提示，不过当你使用了一个 preset，这些命令提示就会被跳过，因为 Vue CLI 假设所有的插件选项都已经在 preset 中声明过了。
|
||||
|
||||
在有些情况下你可能希望 preset 只声明需要的插件，同时让用户通过插件注入的命令提示来保留一些灵活性。
|
||||
|
||||
对于这种场景你可以在插件选项中指定 `"prompts": true` 来允许注入命令提示：
|
||||
|
||||
``` json
|
||||
{
|
||||
"plugins": {
|
||||
"@vue/cli-plugin-eslint": {
|
||||
// 让用户选取他们自己的 ESLint config
|
||||
"prompts": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 远程 Preset
|
||||
|
||||
你可以通过发布 git repo 将一个 preset 分享给其他开发者。这个 repo 应该包含一个包含了 preset 数据的 `preset.json` 文件。然后你就可以在创建项目的时候通过 `--preset` 选项使用这个远程的 preset 了：
|
||||
|
||||
``` bash
|
||||
# 从 GitHub repo 使用 preset
|
||||
vue create --preset username/repo my-project
|
||||
```
|
||||
|
||||
GitLab 和 BitBucket 也是支持的。如果要从私有 repo 获取，请确保使用 `--clone` 选项：
|
||||
|
||||
``` bash
|
||||
vue create --preset gitlab:username/repo --clone my-project
|
||||
vue create --preset bitbucket:username/repo --clone my-project
|
||||
```
|
||||
|
||||
### 加载文件系统中的 Preset
|
||||
|
||||
当开发一个远程 preset 的时候，你必须不厌其烦的向远程 repo 发出 push 进行反复测试。为了简化这个流程，`--preset` 标记也支持本地的 `.json` 文件：
|
||||
|
||||
``` bash
|
||||
vue create --preset local.json my-project
|
||||
```
|
||||
@@ -0,0 +1,70 @@
|
||||
# 快速原型开发
|
||||
|
||||
你可以使用 `vue serve` 和 `vue build` 命令对单个 `*.vue` 文件进行快速原型开发，不过这需要先额外安装一个全局的扩展：
|
||||
|
||||
``` bash
|
||||
npm install -g @vue/cli-service-global
|
||||
```
|
||||
|
||||
`vue serve` 的缺点就是它需要安装全局依赖，这使得它在不同机器上的一致性不能得到保证。因此这只适用于快速原型开发。
|
||||
|
||||
### vue serve
|
||||
|
||||
```
|
||||
Usage: serve [options] [entry]
|
||||
|
||||
在开发环境模式下零配置为 .js 或 .vue 文件启动一个服务器
|
||||
|
||||
|
||||
Options:
|
||||
|
||||
-o, --open 打开浏览器
|
||||
-c, --copy 将本地 URL 复制到剪切板
|
||||
-h, --help 输出用法信息
|
||||
```
|
||||
|
||||
你所需要的仅仅是一个 `App.vue` 文件：
|
||||
|
||||
``` vue
|
||||
<template>
|
||||
<h1>Hello!</h1>
|
||||
</template>
|
||||
```
|
||||
|
||||
然后在这个 `App.vue` 文件所在的目录下运行：
|
||||
|
||||
``` bash
|
||||
vue serve
|
||||
```
|
||||
|
||||
`vue serve` 使用了和 `vue create` 创建的项目相同的默认设置 (webpack、Babel、PostCSS 和 ESLint)。它会在当前目录自动推导入口文件——入口可以是 `main.js`、`index.js`、`App.vue` 或 `app.vue` 中的一个。你也可以显式地指定入口文件：
|
||||
|
||||
``` bash
|
||||
vue serve MyComponent.vue
|
||||
```
|
||||
|
||||
如果需要，你还可以提供一个 `index.html`、`package.json`、安装并使用本地依赖、甚至通过相应的配置文件配置 Babel、PostCSS 和 ESLint。
|
||||
|
||||
### vue build
|
||||
|
||||
```
|
||||
Usage: build [options] [entry]
|
||||
|
||||
在生产环境模式下零配置构建一个 .js 或 .vue 文件
|
||||
|
||||
|
||||
Options:
|
||||
|
||||
-t, --target <target> 构建目标 (app | lib | wc | wc-async, 默认值：app)
|
||||
-n, --name <name> 库的名字或 Web Components 组件的名字 (默认值：入口文件名)
|
||||
-d, --dest <dir> 输出目录 (默认值：dist)
|
||||
-h, --help 输出用法信息
|
||||
```
|
||||
|
||||
你也可以使用 `vue build` 将目标文件构建成一个生产环境的包并用来部署：
|
||||
|
||||
``` bash
|
||||
vue build MyComponent.vue
|
||||
```
|
||||
|
||||
`vue build` 也提供了将组件构建成为一个库或一个 Web Components 组件的能力。查阅[构建目标](./build-targets.md)了解更多。
|
||||
@@ -0,0 +1,190 @@
|
||||
# 配合 webpack
|
||||
|
||||
## 简单的配置方式
|
||||
|
||||
调整 webpack 配置最简单的方式就是在 `vue.config.js` 中的 `configureWebpack` 选项提供一个对象：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
configureWebpack: {
|
||||
plugins: [
|
||||
new MyAwesomeWebpackPlugin()
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
该对象将会被 [webpack-merge](https://github.com/survivejs/webpack-merge) 合并入最终的 webpack 配置。
|
||||
|
||||
::: warning 警告
|
||||
有些 webpack 选项是基于 `vue.config.js` 中的值设置的，所以不能直接修改。例如你应该修改 `vue.config.js` 中的 `outputDir` 选项而不是修改 `output.path`；你应该修改 `vue.config.js` 中的 `baseUrl` 选项而不是修改 `output.publicPath`。这样做是因为 `vue.config.js` 中的值会被用在配置里的多个地方，以确保所有的部分都能正常工作在一起。
|
||||
:::
|
||||
|
||||
如果你需要基于环境有条件地配置行为，或者想要直接修改配置，那就换成一个函数 (该函数会在环境变量被设置之后懒执行)。该方法的第一个参数会收到已经解析好的配置。在函数内，你可以直接修改配置，或者返回一个将会被合并的对象：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
configureWebpack: config => {
|
||||
if (process.env.NODE_ENV === 'production') {
|
||||
// 为生产环境修改配置...
|
||||
} else {
|
||||
// 为开发环境修改配置...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 链式操作 (高级)
|
||||
|
||||
webpack 内部的配置是通过 [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain) 维护的。这个库提供了一个 webpack 原始配置的上层抽象，使其可以定义具名的 loader 规则和具名插件，并有机会在后期进入这些规则并对它们的选项进行修改。
|
||||
|
||||
它允许我们更细粒度的控制其内部配置。接下来有一些常见的在 `vue.config.js` 中的 `chainWebpack` 修改的例子。
|
||||
|
||||
::: tip 提示
|
||||
当你打算链式访问特定的 loader 时，[vue inspect](#审查项目的-webpack-配置) 会非常有帮助。
|
||||
:::
|
||||
|
||||
### 修改 Loader 选项
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
.rule('vue')
|
||||
.use('vue-loader')
|
||||
.loader('vue-loader')
|
||||
.tap(options => {
|
||||
// 修改它的选项...
|
||||
return options
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: tip 提示
|
||||
对于 CSS 相关 loader 来说，我们推荐使用 [css.loasderOptions](../config/#css-loaderoptions) 而不是直接链式指定 loader。这是因为每种 CSS 文件类型都有多个规则，而 `css.loaderOptions` 可以确保你通过一个地方影响所有的规则。
|
||||
:::
|
||||
|
||||
### 添加一个新的 Loader
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
// GraphQL Loader
|
||||
config.module
|
||||
.rule('graphql')
|
||||
.test(/\.graphql$/)
|
||||
.use('graphql-tag/loader')
|
||||
.loader('graphql-tag/loader')
|
||||
.end()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 替换一个规则里的 Loader
|
||||
|
||||
如果你想要替换一个已有的[基础 loader](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-service/lib/config/base.js)，例如为内联的 SVG 文件使用 `vue-svg-loader` 而不是加载这个文件：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
const svgRule = config.module.rule('svg')
|
||||
|
||||
// 清除已有的所有 loader。
|
||||
// 如果你不这样做，接下来的 loader 会附加在该规则现有的 loader 之后。
|
||||
svgRule.uses.clear()
|
||||
|
||||
// 添加要替换的 loader
|
||||
svgRule
|
||||
.use('vue-svg-loader')
|
||||
.loader('vue-svg-loader')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 修改插件选项
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
.plugin('html')
|
||||
.tap(args => {
|
||||
return [/* 传递给 html-webpack-plugin's 构造函数的新参数 */]
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
你需要熟悉 [webpack-chain 的 API](https://github.com/mozilla-neutrino/webpack-chain#getting-started) 并[阅读一些源码](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-service/lib/config)以便了解如何最大程度利用好这个选项，但是比起直接修改 webpack 配置，它的表达能力更强，也更为安全。
|
||||
|
||||
比方说你想要将 `index.html` 默认的路径从 */Users/username/proj/public/index.html* 改为 */Users/username/proj/app/templates/index.html*。通过参考 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin#options) 你能看到一个可以传入的选项列表。我们可以在下列配置中传入一个新的模板路径来改变它：
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
.plugin('html')
|
||||
.tap(args => {
|
||||
args[0].template = '/Users/username/proj/app/templates/index.html'
|
||||
return args
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
你可以通过接下来要讨论的工具 **`vue inspect`** 来确认变更。
|
||||
|
||||
## 审查项目的 webpack 配置
|
||||
|
||||
因为 `@vue/cli-service` 对 webpack 配置进行了抽象，所以理解配置中包含的东西会比较困难，尤其是当你打算自行对其调整的时候。
|
||||
|
||||
`vue-cli-service` 暴露了 `inspect` 命令用于审查解析好的 webpack 配置。那个全局的 `vue` 可执行程序同样提供了 `inspect` 命令，这个命令只是简单的把 `vue-cli-service inspect` 代理到了你的项目中。
|
||||
|
||||
该命令会将解析出来的 webpack 配置、包括链式访问规则和插件的提示打印到 stdout。
|
||||
|
||||
你可以将其输出重定向到一个文件以便进行查阅：
|
||||
|
||||
``` bash
|
||||
vue inspect > output.js
|
||||
```
|
||||
|
||||
注意它输出的并不是一个有效的 webpack 配置文件，而是一个用于审查的被序列化的格式。
|
||||
|
||||
你也可以通过指定一个路径来审查配置的一小部分：
|
||||
|
||||
``` bash
|
||||
# 只审查第一条规则
|
||||
vue inspect module.rules.0
|
||||
```
|
||||
|
||||
或者指向一个规则或插件的名字：
|
||||
|
||||
``` bash
|
||||
vue inspect --rule vue
|
||||
vue inspect --plugin html
|
||||
```
|
||||
|
||||
最后，你可以列出所有规则和插件的名字：
|
||||
|
||||
``` bash
|
||||
vue inspect --rules
|
||||
vue inspect --plugins
|
||||
```
|
||||
|
||||
## 以一个文件的方式使用解析好的配置
|
||||
|
||||
有些外部工具可能需要通过一个文件访问解析好的 webpack 配置，比如那些需要提供 webpack 配置路径的 IDE 或 CLI。在这种情况下你可以使用如下路径：
|
||||
|
||||
```
|
||||
<projectRoot>/node_modules/@vue/cli-service/webpack.config.js
|
||||
```
|
||||
|
||||
该文件会动态解析并输出 `vue-cli-service` 命令中使用的相同的 webpack 配置，包括那些来自插件甚至是你自定义的配置。
|
||||
Reference in New Issue
Block a user