构建配置
- 自动配置
- 手动配置
  - @mpxjs/webpack-plugin
    - options
  - MpxWebpackPlugin.loader
    - options
    - rpx注释样式
    - 例子
  - @mpxjs/url-loader
    - options
    - 内联资源query options
    - 例子
  - output.filename
  - optimization

构建配置

mpx深度定制开发了一个webpack插件@mpxjs/webpack-plugin，基于该插件使用webpack进行小程序的编译构建工作。

自动配置

如果你不熟悉webpack，可以通过脚手架进行快速配置。

手动配置

webpack.config.js

var MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
var webpackConfig = {
  module: {
    rules: [
      // mpx文件必须设置正确的loader，参考下文详细的loader设置options
      {
        test: /\.mpx$/,
        use: MpxWebpackPlugin.loader({
          // `only`模式下，样式前加上注释/* use rpx */可将该段样式中所有的px转换为rpx
          transRpx: 'only',
          comment: 'use rpx'
        })
      },
      // 对本地图片资源提供增强，编译成小程序支持的格式 
      // <style>中的图片会被强制转为base64，
      // 其他地方引用的资源小于limit的会被转base64，否则会被打包到dist/img目录下通过小程序路径引用
      // 由于微信小程序中<cover-image>不支持传base64，可以在图像资源链接后加上`?fallback`查询字符串强制跳过转base64步骤
      // 参考下文详细的设置@mpxjs/url-loader的方法
      {
        test: /\.(png|jpe?g|gif|svg)(\?.*)?$/,
        loader: '@mpxjs/url-loader',
        options: {
          limit: 10000,
          name: 'img/[name].[ext]'
        }
      }
    ]
  },
  // mpx主插件，必须设置，参考下文详细的插件设置options
  plugins: [
    new MpxWebpackPlugin({
    // 微信模式下设置为`wx`，支付宝模式下设置为`ali`
      mode: 'wx'
    })
  ],
  // sourceMap: 小程序不支持eval，因此不要设置为eval相关的sourceMap类型。
  // 注意：webpack4新增的mode属性设置为development的时候，会将devtool默认设置为eval，
  //      必须手动设置devtool为非eval相关类型来覆盖默认配置
  devtool: false,
  output: {
    // filename设置不能更改
    filename: '[name].js' 
  },
  // 通过webpack分包能力减少小程序体积，参考下文的详细介绍
  optimization: {
    runtimeChunk: {
      name: 'bundle'
    },
    splitChunks: {
      chunks: 'all',
      name: 'bundle',
      minChunks: 2
    }
  }
}

@mpxjs/webpack-plugin

webpack.config.js

var MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
webpackconfig = {
  plugins: [
    new MpxWebpackPlugin(options)
  ],
}

options

mode

String
- wx代表编译微信小程序
- ali代表编译支付宝程序

MpxWebpackPlugin.loader

@mpxjs/webpack-plugin暴露了一个静态方法MpxWebpackPlugin.loader作为.mpx文件的loader

webpack.config.js

var MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
webpackconfig = {
  module: {
    rules: [
      {
        test: /\.mpx$/,
        use: MpxWebpackPlugin.loader(options)
      }
    ]
  }
}

options

transRpx

Object | boolean | string
- false关闭转换rpx
- 'all'普通样式中的px全部转换为rpx，rpx注释样式不转换
- 'only'普通样式中的px全部不转换为rpx，rpx注释样式转换
- Object包含属性：mode/comment/designWidth/include/exclude
  
  include/exclude属性的用法和webpack对module.rules里的规则是一样的，参考webpack文档-exclude
comment (即将废弃外层写法，迁移至transRpx内层)

String

<style>中的注释内容与options.comment一致时，会被识别为一个rpx注释
designWidth (即将废弃外层写法，迁移至transRpx内层)

Number

设计稿宽度，单位为px。默认值为750px。

mpx会基于小程序标准的屏幕宽度baseWidth 750rpx，与option.designWidth计算出一个转换比例transRatio

转换比例的计算方式为transRatio = (baseWidth / designWidth)。精度为小数点后2位四舍五入

所有生效的rpx注释样式中的px会乘上transRatio得出最终的rpx值

例如：
```
/* 转换前：designWidth = 1280 */
.btn {
  width: 200px;
  height: 100px;
}
/* 转换后: transRatio = 0.59 */
.btn {
  width: 118rpx;
  height: 59rpx;
}
```

rpx注释样式

根据rpx注释的位置，mpx会将一段css规则或者一条css声明视为rpx注释样式

开发者可以声明一段rpx注释样式，提示编译器是否转换这段css中的px

例子

全局转换px至rpx，除了某些rpx注释样式之外

webpack.config.js

webpackconfig = {
  module: {
    rules: [
      {
        test: /\.mpx$/,
        use: MpxWebpackPlugin.loader({
          transRpx: {
            mode: 'all',
            comment: 'use px',
            designWidth: 750,
            include: resolve('src')
          },
        })
      }
    ]
  }
}

index.mpx

<style lang="css">
  /* use px */
  .not-translate-a {
    font-size: 100px;
    padding: 10px;
  }
  .not-translate-b {
    /* use px */
    font-size: 100px;
    padding: 10px;
  }
  .translate-a {
    font-size: 100px;
    padding: 10px;
  }
  .translate-b {
    font-size: 100px;
    padding: 10px;
  }
</style>

第一个注释位于一个选择器前，是一个css规则注释，整个规则都会被视为rpx注释样式

第二个注释位于一个css声明前，是一个css声明注释，只有font-size: 100px会被视为rpx注释样式

transRpx = all模式下，除了这两条rpx注释样式之外，其他都会转rpx

只对某些rpx注释样式进行转rpx，全局其他px不转

webpack.config.js

webpackconfig = {
  module: {
    rules: [
      {
        test: /\.mpx$/,
        use: MpxWebpackPlugin.loader({
          transRpx: 'only',
          comment: 'use rpx',
          designWidth: 750
        })
      }
    ]
  }
}

index.mpx

<style lang="css">
  .not-translate-a {
    font-size: 100px;
    padding: 10px;
  }
  .not-translate-b {
    font-size: 100px;
    padding: 10px;
  }
  /* use rpx */
  .translate-a {
    font-size: 100px;
    padding: 10px;
  }
  .translate-b {
    /* use rpx */
    font-size: 100px;
    padding: 10px;
  }
</style>

第一个注释位于一个选择器前，是一个css规则注释，整个规则都会被视为rpx注释样式

第二个注释位于一个css声明前，是一个css声明注释，只有font-size: 100px会被视为rpx注释样式

transRpx = only模式下，只有这两条rpx注释样式会转rpx，其他都不转

@mpxjs/url-loader

受限于小程序既有的能力，目前在小程序中加载本地图片资源会有诸多限制：

<style>中的css属性值只能使用base64引用图片，无法用本地路径
<template>中的<cover-image>组件的src属性只能通过本地路径，不能使用base64
<template>中的其他组件，例如<image>的src属性既可以用本地路径，又可以用base64

@mpxjs/url-loader对这些限制提供了增强。开发者在源码中无需书写base64，通过统一的路径方式引入图片资源，最终编译成小程序支持的代码。

想深入的了解@mpxjs/url-loader对小程序对图片资源的支持，查看mpx图像资源处理了解更多细节

安装

npm install @mpxjs/url-loader

webpack.config.js

webpackconfig = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif|svg)(\?.*)?$/,
        loader: '@mpxjs/url-loader',
        options: /* options */
      }
    ]
  }
}

options

仅对<template>和<script>中的资源生效，因为<style>里的资源会强制做base64

limit

Number

单位为byte，小于limit的资源会被base64，反之会被打包成资源
name

String

设置图片被打包后的路径: 'img/[name].[ext]'

内联资源query options

fallback

Any

通过内联query options，可以对指定的资源强制使用资源打包。

这对于<cover-image>组件引用图片资源非常有效，因为<cover-image>组件不能用base64

例子

文件目录

  component
  │-- index.mpx 
  │-- bg-img1.png    
  │-- bg-img2.png    
  │-- bg-img3.png

webpack.config.js

webpackconfig = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif|svg)(\?.*)?$/,
        loader: '@mpxjs/url-loader',
        otions: {
          limit: 10000,
          name: 'img/[name].[ext]'
        } 
      }
    ]
  }
}

index.mpx

<template>
  <image src="./bg-img1.png"></image>
  <image src="./bg-img2.png"></image>
  <cover-image src="./bg-img3.png?fallback">
</template>

bg-img1.png大于10KB，会被打包成资源

bg-img2.png小于10KB，会被做base64

bg-img3.png需要在路径后添加fallback强制打包资源

output.filename

小程序限定描述页面的文件具有相同的路径和文件名，仅以后缀名进行区分。

因此output.filename中必须写为 [name].js，基于chunk id或者hash name的filename都会导致编译后的文件无法被小程序识别

webpack.config.js

webpackconfig = {
  output: {
    filename: '[name].js', // 正确 
    filename: '[id].js', // 错误。chunk id name
    filename: '[name].[chunkhash].js' // 错误。hash name
  }
}

optimization

为了减少打包后app/page/component目录中的js文件体积。mpx提供了抽取公共依赖的能力。将共用的依赖进行统一抽取

通过optimization.runtimeChunk和optimization.splitChunks进行设置

webpack.config.js

webpackConfig = {
  optimization: {
    runtimeChunk: {
      name: 'bundle'
    },
    splitChunks: {
      cacheGroups: {
        bundle: {
          chunks: 'all',
          name: 'bundle',
          minChunks: 2
        }
      }
    }
  }
}