@mpxjs/cli

基于 @vue/cli 开发的 mpx 脚手架。

• @mpxjs/cli
  • 安装
  • 使用
  • 基础
    • CLI 命令
      • create
      • build
      • serve
  • 开发
    • webpack 相关
      • mpx 编译构建配置
      • 根据不同的构建目标配置
      • 调试 webpack 配置
    • css 相关
      • css 预编译
      • postcss
    • template 相关
  • 配置
    • mpx.config.js
  • mpx-cli 插件 1.0 升级到 2.0
  • 开发插件
  • cli 相关介绍

安装

npm i @mpxjs/cli -g

如果插件版本是1.x，需要前往https://github.com/mpx-ecology/mpx-cli/tree/master 查看文档

使用

mpx create project-name
cd project-name
npm run build

相关命令

{
  "serve": "mpx-cli-service serve", // 开发模式
  "build": "mpx-cli-service build" // 构建模式
}

基础

CLI 命令

create

用法: mpx create [options] <app-name>

选项:

  -p, --preset <presetName>       使用已保存或远程预设
  -d, --default                   使用默认预设
  -i, --inlinePreset <json>       使用行内预设
  -m, --packageManager <command>  在安装依赖项时使用指定的npm管理器
  -r, --registry <url>            在安装依赖项时使用指定的npm源（仅适用于npm）
  -g, --git [message]             使用初始提交消息强制git初始化
  -n, --no-git                    跳过git初始化
  -f, --force                     如果目标目录存在，则覆盖该目录
  --merge                         合并目标目录（如果存在）
  -c, --clone                     使用git克隆获取远程预置
  -x, --proxy <proxyUrl>          创建项目时使用指定的代理

RN项目不支持pnpm，请在创建输出到RN项目时指定 mpx create -m npm 来创建项目

build

用法：mpx-cli-service build [options]

选项:

  --targets    编译目标(默认值: wx)
  --mode       指定环境模式 (默认值：production)
  --env        自定义 __mpx_env__
  --watch      监听文件变化
  --report     生成包分析报告

# 构建小程序，默认微信
mpx-cli-service build --targets=wx,ali

目前支持的平台

平台	target
微信	wx
阿里	ali
百度	swan
QQ	qq
头条	tt
浏览器	web
react-native(安卓)	android
react-native(IOS)	ios

serve

用法：mpx-cli-service serve [options]

选项:

  --targets    编译到小程序目标(默认值: wx)
  --mode       指定环境模式 (默认值：production)
  --env        自定义 __mpx_env__

开发

webpack 相关

mpx 编译构建配置

新版的 @mpxjs/cli 整体是基于 @vue/cli 的架构设计开发的。因此有关 mpx 编译构建相关的配置统一使用 mpx.config.js 来进行管理。

有关 mpx 相关的 webpack 插件、loader 等在 mpx.config.js 当中 pluginOptions.mpx 进行相关的配置：

// mpx.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 初始化的项目提供了开箱即用的配置(在插件内部设置了默认的配置)，如果开发过程中有一些其他的配置需求，参见 mpx 官方文档。

根据不同的构建目标配置

可根据构建平台和开发环境进行选择性的配置，在构建过程中暴露出来的环境变量包括：

• MPX_CLI_MODE: 'mp' | 'web'
• NODE_ENV：'development' | 'production'
• MPX_CURRENT_TARGET_MODE: 'wx' | 'ali' | 'swan' | 'qq' | 'tt' | 'dd' | 'web'
• MPX_CURRENT_TARGET_ENV : 'development' | 'production'

// mpx.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
    }
  }
}

调试 webpack 配置

可以使用 mpx inspect 以及 mpx inspect 调试 webpack 配置。

可以将其输出重定向到一个文件以便进行查阅。

mpx inspect > output.js

还可以增加targets,mode等选项来输出针对不同条件下的配置。

mpx inspect --targets=wx,ali --mode=development

css 相关

css 预编译

通过 mpx-cli 初始化的项目内置 stylus 作为 css 的预编译处理器。

同时在 webpack 构建配置当中也预置了 sass、less 这 2 个预编译处理器的配置。如果你的项目需要使用这 2 种预编译器，安装对应的预编译处理工具即可：

# Sass
npm install -D sass-loader sass

# Less
npm install -D less-loader less

postcss

创建postcss.config.js即可

也可以使用mpx配置postcssInlineConfig的方式.

// postcss.config.js
module.exports = {
  plugins: {
    // 'postcss-import': {},
    // 'postcss-preset-env': {},
    // 'cssnano': {},
    // 'autoprefixer': {}
  }
}

template 相关

可以使用任何模板语言来编译 template，只需要在 template 上添加 lang 属性. mpx-cli 内置了 pug 模板配置，如果需要使用 pug 模板，只需要安装 pug 依赖即可。

<template lang="pug"></template>

然后安装相关依赖即可

npm install -D pug pug-plain-loader

配置

mpx.config.js

以下表格为 mpx.config.js 当中 web 侧和 小程序 侧支持的字段一览表，具体每个字段的配置功能请参见 @vue/cli 官方配置：

注：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	-

可通过 mpx.config.js 中提供的 chainWebpack 或 configureWebpack 字段进行配置，具体使用规则请参见@vue/cli：

// mpx.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 插件 1.0 升级到 2.0

插件 1.0 和 2.0 在构建流程上做了很大的改动，所以如果需要从 1.0 升级到 2.0，需要做以下改动

1. npm uninstall @mpxjs/vue-cli-plugin-mpx-mp @mpxjs/vue-cli-plugin-mpx-web
2. 修改 package.json 里的build:mp为build,serve:mp为serve

之后正常运行命令即可

开发插件

一个 CLI 插件是一个 npm 包，它能够为 MPX CLI 创建的项目添加额外的功能，这些功能包括：

• 修改项目的 webpack 配置
• 添加新的mpx-cli-service命令
• 扩展 package.json
• 在项目中创建新文件、或者修改老文件。
• 提示用户选择一个特定的选项

开发插件

cli 相关介绍

包名	版本	描述
@mpxjs/cli		mpx-cli
@mpxjs/mpx-cli-service		mpx-cli 服务
@mpxjs/vue-cli-plugin-mpx		mpx-cli 核心插件，包含基础配置，文件模板等
@mpxjs/vue-cli-plugin-mpx-eslint		eslint 插件，包含 eslint 相关配置
@mpxjs/vue-cli-plugin-mpx-cloud-func		云函数编译构建插件
@mpxjs/vue-cli-plugin-mpx-mp		小程序插件，包含小程序构建，开发命令，以及相关配置等
@mpxjs/vue-cli-plugin-mpx-web		web 插件，包含 web 构建，开发命令，以及相关配置等
@mpxjs/vue-cli-plugin-mpx-unit-test		单测插件，包含单元测试相关配置
@mpxjs/vue-cli-plugin-mpx-plugin-mode		小程序插件模式插件，包含小程序插件的 js，ts 模板等
@mpxjs/vue-cli-plugin-mpx-typescript		ts 插件，包含小程序 ts 模板以及相关配置等