Merge pull request #1744 from didi/docs-add-cli-readme

docs: 修改快速开始部分文档&添加编译配置修改指南

docs-vuepress/.vuepress/config.js

@@ -43,7 +43,8 @@ const sidebar = {
         'advance/custom-output-path',
         'advance/utility-first-css',
         'advance/ssr',
-        'advance/provide-inject'
+        'advance/provide-inject',
+        'advance/build-config'
       ]
     },
     {

docs-vuepress/guide/advance/build-config.md

@@ -0,0 +1,114 @@
+# 编译配置
+
+新版的 `@mpxjs/cli` 整体是基于 `@vue/cli` 的架构设计开发的。因此有关 `mpx` 编译构建相关的配置统一使用 `vue.config.js` 来进行管理。
+
+### 编译构建配置
+
+#### mpx 编译构建配置
+
+有关 `mpx` 相关的 webpack 插件、loader 等在 `vue.config.js` 当中 `pluginOptions.mpx` 进行相关的配置：
+
+```javascript
+// vue.config.js
+module.exports = {
+  pluginOptions: {
+    mpx: {
+      // 传入 @mpxjs/webpack-plugin 当中的配置信息
+      // 具体可参考文档：https://www.mpxjs.cn/api/compile.html#mpxwebpackplugin-options
+      plugin: {
+        srcMode: 'wx',
+      },
+      // 传入 @mpxjs/webpack-plugin loader 当中的配置信息
+      // 具体可参考文档：https://www.mpxjs.cn/api/compile.html#mpxwebpackplugin-loader
+      loader: {},
+      // 提供图片资源处理简单操作
+      // 具体配置参考 https://mpxjs.cn/guide/advance/image-process.html#%E5%9B%BE%E5%83%8F%E8%B5%84%E6%BA%90%E5%BC%95%E5%85%A5%E6%9C%89%E4%B8%89%E7%A7%8D%E6%96%B9%E5%BC%8F
+      urlLoader: {
+        name: 'img/[name][hash].[ext]',
+        publicPath: '',
+        publicPathScope: '',
+        limit: 10
+      }
+    }
+  }
+}
+```
+
+注：通过 `@mpxjs/cli` 初始化的项目提供了开箱即用的配置(在[插件内部](https://github.com/mpx-ecology/mpx-cli/blob/master/packages/vue-cli-plugin-mpx/utils/resolveMpxWebpackPluginConf.js#L6-L59)设置了默认的配置)，如果开发过程中有一些其他的配置需求，参见 [mpx 官方文档](https://www.mpxjs.cn/api/compile.html#mpxwebpackplugin-options)。
+
+#### vue.config.js
+
+以下表格为 `vue.config.js` 当中 `web` 侧和 `小程序` 侧支持的字段一览表，具体每个字段的配置功能请参见 [@vue/cli 官方配置](https://cli.vuejs.org/config/#configuration-reference)：
+
+注：`yes` 表示在对应环境支持配置，`no` 表示在对应环境不支持配置。
+
+| 字段                       | web | 小程序 | 备注                                                          |
+| -------------------------- | --- | ------ | ------------------------------------------------------------- |
+| publicPath                 | yes | no     | -                                                             |
+| outputDir                  | yes | yes    | `dist/${process.env.MPX_CURRENT_TARGET_MODE}`目录作为输出目录 |
+| assetsDir                  | yes | no     | -                                                             |
+| indexPath                  | yes | no     | -                                                             |
+| filenameHashing            | yes | no     | -                                                             |
+| pages                      | yes | no     | -                                                             |
+| lintOnSave                 | yes  | yes     | -                                                             |
+| runtimeCompiler            | yes | no     | -                                                             |
+| transpileDependencies      | yes | yes    | -                                                             |
+| productionSourceMap        | yes | yes    |                                                   |
+| crossorigin                | yes | no     | -                                                             |
+| integrity                  | yes | no     | -                                                             |
+| configureWebpack           | yes | yes    | -                                                             |
+| chainWebpack               | yes | yes    | -                                                             |
+| css.requireModuleExtension | yes | no     | -                                                             |
+| css.extract                | yes | no     | -                                                             |
+| css.sourceMap              | yes | no     | 未来会支持                                                    |
+| css.loaderOptions          | yes | no     | 未来会支持                                                    |
+| devServer                  | yes | no     | -                                                             |
+| devServer.proxy            | yes | no     | -                                                             |
+| parallel                   | yes | no     | -                                                             |
+| pwa                        | yes | no     | -                                                             |
+| pluginOptions              | yes | yes    | -                                                             |
+
+可通过 `vue.config.js` 中提供的 `chainWebpack` 或 `configureWebpack` 字段进行配置，具体使用规则请参见[@vue/cli](https://cli.vuejs.org/guide/webpack.html#simple-configuration)：
+
+```javascript
+// vue.config.js
+module.exports = {
+  configureWebpack: {
+    plugins: [new MyOwnWebpackPlugin()]
+  },
+  chainWebpack: (config) => {
+    config
+      .rule('some-rule')
+      .test(/some-rule/)
+      .use('some-loader')
+      .loader('some-loader')
+  }
+}
+```
+
+### 根据不同的构建目标配置
+
+可根据构建平台和开发环境进行选择性的配置，在构建过程中暴露出来的环境变量包括：
+
+- `MPX_CLI_MODE`: 'mp' | 'web' | 'rn'
+- `NODE_ENV`：'development' | 'production'
+- `MPX_CURRENT_TARGET_MODE`: 'wx' | 'ali' | 'swan' | 'qq' | 'tt' | 'dd' | 'web' | 'ios' | 'android' | 'harmony'
+- `MPX_CURRENT_TARGET_ENV` : 'development' | 'production'
+
+```javascript
+// vue.config.js
+module.exports = {
+  chainWebpack: (config) => {
+    if (process.env.MPX_CLI_MODE === 'mp') {
+      // do something
+    }
+
+    if (
+      process.env.MPX_CLI_MODE === 'web' &&
+      process.env.NODE_ENV === 'development'
+    ) {
+      // do something
+    }
+  }
+}
+```

docs-vuepress/guide/basic/start.md

@@ -31,12 +31,68 @@ npm install
 
 ## 编译构建
 
+相关命令
+
+```json
+{
+  "serve": "mpx-cli-service serve", // 开发模式
+  "build": "mpx-cli-service build" // 构建模式
+}
+```
+
 使用npm script执行mpx的编译构建，在开发模式下我们执行serve命令，将项目源码构建输出到`dist/${平台目录}`下，并且监听源码的改动进行重新编译。
 
 ```shell
 npm run serve
 ```
 
+### CLI 命令
+
+#### build
+
+```sh
+用法：mpx-cli-service build [options]
+
+选项:
+
+  --targets    编译目标(默认值: wx)
+  --mode       指定环境模式 development | production (默认值：production)
+  --env        自定义 __mpx_env__
+  --watch      监听文件变化
+  --report     生成包分析报告
+```
+```sh
+# 构建小程序，默认微信
+mpx-cli-service build --targets=wx,ali
+```
+
+**目前支持的平台**
+
+| 平台  | target  |
+|-----|---------|
+| 微信  | wx      |
+| 阿里  | ali     |
+| 百度  | swan    |
+| QQ  | qq      |
+| 头条  | tt      |
+| 浏览器 | web     |
+| 安卓  | android |
+| iOS | ios     |
+| 鸿蒙  | harmony |
+
+
+#### serve
+
+```sh
+用法：mpx-cli-service serve [options]
+
+选项:
+
+  --targets    编译到小程序目标(默认值: wx)
+  --mode       指定环境模式 (默认值：production)
+  --env        自定义 __mpx_env__
+```
+
 ## 预览调试
 使用小程序开发者工具打开dist下对应平台的目录，对你的小程序进行预览、调试，详情可参考[小程序开发指南](https://developers.weixin.qq.com/miniprogram/dev/framework/quickstart/getstart.html)
 
@@ -165,6 +221,3 @@ npm run build:cross
 ```
 
 关于跨平台能力的更多详情请查看[这里](../advance/platform.md)
-
-
-