编译配置详情

sourceRoot

string

默认值:'src'

源码存放目录。

outputRoot

string

默认值:'dist'

代码编译后的生产目录。

designWidth

number

默认值:750

设计稿尺寸,详情请见设计稿及尺寸单位

defineConstants

object

用于配置一些全局变量供代码中进行使用。

配置方式可参考 Webpack DefinePlugin,例如:

/config/index.js

  1. module.exports = {
  2. // ...
  3. defineConstants: {
  4. A: '"a"' // JSON.stringify('a')
  5. }
  6. }

alias

object

用于配置目录别名,从而方便书写代码引用路径。

例如,使用相对路径书写文件引用如下:

  1. import A from '../../componnets/A'
  2. import Utils from '../../utils'
  3. import packageJson from '../../package.json'
  4. import projectConfig from '../../project.config.json'

为了避免书写多级相对路径,我们可以如下配置 alias

  1. module.exports = {
  2. // ...
  3. alias: {
  4. '@/components': path.resolve(__dirname, '..', 'src/components'),
  5. '@/utils': path.resolve(__dirname, '..', 'src/utils'),
  6. '@/package': path.resolve(__dirname, '..', 'package.json'),
  7. '@/project': path.resolve(__dirname, '..', 'project.config.json'),
  8. }
  9. }

通过上述配置,可以将 src/componentssrc/utils 目录配置成别名,将根目录下的 package.jsonproject.config.json 文件配置成别名,则代码中的引用改写如下:

  1. import A from '@/components/A'
  2. import Utils from '@/utils'
  3. import packageJson from '@/package'
  4. import projectConfig from '@/project'

为了让编辑器(VS Code)不报错,并继续使用自动路径补全的功能,需要在项目根目录下的 jsconfig.json 或者 tsconfig.json 中配置 paths 让编辑器认得我们的别名,形式如下:

  1. {
  2. "compilerOptions": {
  3. "baseUrl": ".",
  4. "paths": {
  5. "@/components/*": ["./src/components/*"],
  6. "@/utils/*": ["./src/utils/*"],
  7. "@/package": ["./package.json"],
  8. "@/project": ["./project.config.json"],
  9. }
  10. }
  11. }

建议别名使用 @/ 开头而非仅用 @ 开头,因为有小概率会与某些 scoped 形式的 npm 包(形如:@tarojs/taro, @babel/core)产生命名冲突。

env

object

用于设置环境变量,如 process.env.NODE_ENV

假设我们需要区分开发环境和生产环境,可以如下配置:

config/dev.js

/config/dev.js

  1. module.exports = {
  2. // ...
  3. env: {
  4. NODE_ENV: '"development"' // JSON.stringify('development')
  5. }
  6. }

config/prod.js

config/prod.js

  1. module.exports = {
  2. // ...
  3. env: {
  4. NODE_ENV: '"production"' // JSON.stringify('production')
  5. }
  6. }

这样就能在代码中通过 process.env.NODE_ENV === 'development' 来判断环境。

copy

object

用于把文件从源码目录直接拷贝到编译后的生产目录。

copy.patterns

array

用于指定需要拷贝的文件或者目录,每一项都必须包含 fromto 配置,分别代表来源和需要拷贝到的目录。同时可以设置 ignore 配置来指定需要忽略的文件, ignore 是指定的 glob 类型字符串,或者 glob 字符串数组。

注意,from 必须指定存在的文件或者目录,暂不支持 glob 格式。fromto 直接置顶项目根目录下的文件目录,建议 fromsrc 目录开头,todist 目录开头。

一般有如下的使用形式:

  1. module.exports = {
  2. // ...
  3. copy: {
  4. patterns: [
  5. { from: 'src/asset/tt/', to: 'dist/asset/tt/', ignore: ['*.js'] }, // 指定需要 copy 的目录
  6. { from: 'src/asset/tt/sd.jpg', to: 'dist/asset/tt/sd.jpg' } // 指定需要 copy 的文件
  7. ]
  8. }
  9. }

copy.options

object

拷贝配置,可以指定全局的 ignore:

  1. module.exports = {
  2. // ...
  3. copy: {
  4. options: {
  5. ignore: ['*.js', '*.css'] // 全局的 ignore
  6. }
  7. }
  8. }

plugins

array

配置 Taro 插件。

当不需要传入参数给插件时,以下写法等价:

  1. module.exports = {
  2. // ...
  3. plugins: [
  4. // 从本地绝对路径引入插件
  5. '/absulute/path/plugin/filename',
  6. // 引入 npm 安装的插件
  7. '@tarojs/plugin-mock',
  8. ['@tarojs/plugin-mock'],
  9. ['@tarojs/plugin-mock', {}]
  10. ]
  11. }

给插件传参:

  1. module.exports = {
  2. // ...
  3. plugins: [
  4. // 引入 npm 安装的插件,并传入插件参数
  5. ['@tarojs/plugin-mock', {
  6. mocks: {
  7. '/api/user/1': {
  8. name: 'judy',
  9. desc: 'Mental guy'
  10. }
  11. }
  12. }]
  13. ]
  14. }

presets

array

一个 preset 是一系列 Taro 插件的集合,配置语法同 plugins

  1. module.exports = {
  2. // ...
  3. presets: [
  4. // 引入 npm 安装的插件集
  5. '@tarojs/preset-sth',
  6. // 引入 npm 安装的插件集,并传入插件参数
  7. ['@tarojs/plugin-sth', {
  8. arg0: 'xxx'
  9. }],
  10. // 从本地绝对路径引入插件集,同样如果需要传入参数也是如上
  11. '/absulute/path/preset/filename',
  12. ]
  13. }

terser

object

配置 terser 工具以压缩 JS 代码。

terser.enable

boolean

默认值 true

是否开启 JS 代码压缩。

terser.config

object

terser 的具体配置。

  1. module.exports = {
  2. // ...
  3. terser: {
  4. enable: true,
  5. config: {
  6. // 配置项同 https://github.com/terser/terser#minify-options
  7. }
  8. }
  9. }

terser 配置只在生产模式下生效。如果你正在使用 watch 模式,又希望启用 terser,那么则需要设置 process.env.NODE_ENV'production'

csso

object

配置 csso 工具以压缩 CSS 代码。

csso.enable

boolean

默认值 true

是否开启 CSS 代码压缩。

csso.config

object

csso 的具体配置。

  1. module.exports = {
  2. // ...
  3. csso: {
  4. enable: true,
  5. config: {
  6. // 配置项同 https://github.com/css/csso#minifysource-options
  7. }
  8. }
  9. }

csso 配置只在生产模式下生效。如果你正在使用 watch 模式,又希望启用 csso,那么则需要设置 process.env.NODE_ENV'production'

sass

object

用于控制对 scss 代码的编译行为,默认使用 dart-sass,具体配置可以参考 sass

当需要往所有 scss 文件头部插入 scss 代码时,可以通过以下三个额外参数设置:

sass.resource

string | array

需要全局注入的 scss 文件的绝对路径。如果要引入多个文件,支持以数组形式传入。

当存在 projectDirectory 配置时,才支持传入相对路径。

sass.projectDirectory

string

项目根目录的绝对地址(若为小程序云开发模板,则应该是client目录)。

sass.data

string

全局 scss 变量,若 data 与 resource 中设置了同样的变量,则 data 的优先级高于 resource。

全局注入 scss 的例子

单文件路径形式

当只有 resource 字段时,可以传入 scss 文件的绝对路径。

  1. module.exports = {
  2. // ...
  3. sass: {
  4. resource: path.resolve(__dirname, '..', 'src/styles/variable.scss')
  5. }
  6. }

多文件路径形式

此外,当只有 resource 字段时,也可以传入一个路径数组。

  1. module.exports = {
  2. // ...
  3. sass: {
  4. resource: [
  5. path.resolve(__dirname, '..', 'src/styles/variable.scss'),
  6. path.resolve(__dirname, '..', 'src/styles/mixins.scss')
  7. ]
  8. }
  9. }

指定项目根目录路径形式

你可以额外配置 projectDirectory 字段,这样你就可以在 resource 里写相对路径了。

  1. module.exports = {
  2. // ...
  3. sass: {
  4. resource: [
  5. 'src/styles/variable.scss',
  6. 'src/styles/mixins.scss'
  7. ],
  8. projectDirectory: path.resolve(__dirname, '..')
  9. }
  10. }

传入 scss 变量字符串

data 中声明的 $nav-height 变量优先级最高。

  1. module.exports = {
  2. // ...
  3. sass: {
  4. resource: [
  5. 'src/styles/variable.scss',
  6. 'src/styles/mixins.scss'
  7. ],
  8. projectDirectory: path.resolve(__dirname, '..'),
  9. data: '$nav-height: 48px;'
  10. }
  11. }

mini

object

专属于小程序的配置。

mini.baseLevel

number

默认值:16

对于 template 模板不支持递归的小程序(如:微信、QQ、京东),Taro 会对所有模板循环 baseLevel 次,以支持同类模板的循环调用。

但是循环太多次也会导致生成的 base 模板体积相当大,因此当你的嵌套层级并不太深时可以使用 baseLevel 配置项配置较少的循环层数。

当然在嵌套层级较深时,也可以增大 baseLevel。以避免到达循环上限后,Taro 会调用一个自定义组件重新开始循环所带来一些问题。

mini.compile

object

小程序编译过程的相关配置。

mini.compile.exclude

array

配置小程序编译过程中排除不需要经过 Taro 编译的文件,数组里面可以包含具体文件路径,也可以是判断函数,同 Rule.exclude

假设要排除某个文件,可以配置要排除的文件的具体路径:

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. compile: {
  6. exclude: [
  7. path.resolve(__dirname, '..', 'src/pages/index/vod-wx-sdk-v2.js')
  8. ]
  9. }
  10. }
  11. }

也可以配置判断函数:

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. compile: {
  6. exclude: [
  7. modulePath => modulePath.indexOf('vod-wx-sdk-v2') >= 0
  8. ]
  9. }
  10. }
  11. }

mini.compile.include

array

配置额外需要经过 Taro 编译的文件,使用方式与 mini.compile.exclude 一致,同 Rule.include

例如 Taro 默认不编译 node_modules 中的文件,可以通过这个配置让 Taro 编译 node_modules 中的文件。

mini.webpackChain

function

自定义 Webpack 配置。

这个函数会收到三个参数。第一个参数是 webpackChain 对象,可参考 webpack-chain 的 API 进行修改,第二个参数是 webpack 实例,第三个参数 PARSE_AST_TYPE 是小程序编译时的文件类型集合。

第三个参数的取值如下:

  1. export enum PARSE_AST_TYPE {
  2. ENTRY = 'ENTRY',
  3. PAGE = 'PAGE',
  4. COMPONENT = 'COMPONENT',
  5. NORMAL = 'NORMAL',
  6. STATIC = 'STATIC'
  7. }

例子:

  1. // 这是一个添加 raw-loader 的例子,用于在项目中直接引用 md 文件
  2. module.exports = {
  3. // ...
  4. mini: {
  5. // ...
  6. webpackChain (chain, webpack) {
  7. chain.merge({
  8. module: {
  9. rule: {
  10. myloader: {
  11. test: /\.md$/,
  12. use: [{
  13. loader: 'raw-loader',
  14. options: {}
  15. }]
  16. }
  17. }
  18. }
  19. })
  20. }
  21. }
  22. }
  1. // 这是一个添加插件的例子
  2. module.exports = {
  3. // ...
  4. mini: {
  5. // ...
  6. webpackChain (chain, webpack) {
  7. chain.merge({
  8. plugin: {
  9. install: {
  10. plugin: require('npm-install-webpack-plugin'),
  11. args: [{
  12. // Use --save or --save-dev
  13. dev: false,
  14. // Install missing peerDependencies
  15. peerDependencies: true,
  16. // Reduce amount of console logging
  17. quiet: false,
  18. // npm command used inside company, yarn is not supported yet
  19. npm: 'cnpm'
  20. }]
  21. }
  22. }
  23. })
  24. }
  25. }
  26. }

mini.output

object

可用于修改、拓展 Webpack 的 output 选项,配置项参考官方文档

mini.enableSourceMap

boolean

默认值:watch 模式下为 true,否则为 false

用于控制是否生成 js、css 对应的 sourceMap。

mini.sourceMapType

string

默认值:'cheap-module-source-map'

具体配置请参考 Webpack devtool 配置

mini.debugReact

自 v3.0.8 开始支持

boolean

默认值:false

指定 React 框架相关的代码是否使用开发环境(未压缩)代码,默认使用生产环境(压缩后)代码。

mini.minifyXML

自 v3.0.8 开始支持

object

关于压缩小程序 xml 文件的相关配置。

mini.minifyXML.collapseWhitespace

boolean

默认值:false

是否合并 xml 文件中的空格。

mini.postcss

object

配置 postcss 相关插件。

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. postcss: {
  6. // 可以进行 autoprefixer 的配置。配置项参考官方文档 https://github.com/postcss/autoprefixer
  7. autoprefixer: {
  8. enable: true,
  9. config: {
  10. // autoprefixer 配置项
  11. }
  12. },
  13. pxtransform: {
  14. enable: true,
  15. config: {
  16. // pxtransform 配置项,参考尺寸章节
  17. selectorBlackList: ['body']
  18. }
  19. },
  20. // 小程序端样式引用本地资源内联
  21. url: {
  22. enable: true,
  23. config: {
  24. limit: 10240 // 设定转换尺寸上限
  25. }
  26. },
  27. // css modules 功能开关与相关配置
  28. cssModules: {
  29. enable: false, // 默认为 false,如需使用 css modules 功能,则设为 true
  30. config: {
  31. generateScopedName: '[name]__[local]___[hash:base64:5]'
  32. }
  33. }
  34. }
  35. }
  36. }

mini.commonChunks

array | function

用于告诉 Taro 编译器需要抽取的公共文件,支持两种配置方式。

commonChunks 的配置值必须依据于 webpack 配置 optimization.runtimeChunkoptimization.splitChunks 中的公共 chunks 的名称。Taro 中 webpack.optimization 配置的默认值:源码位置

如果有自行拆分公共文件的需求,请先通过 webpackChain 配置 覆盖optimization.runtimeChunkoptimization.splitChunks 配置。再通过此 commonChunks 配置指定公共入口文件。

字符串数组方式

普通编译时的默认值:['runtime', 'vendors', 'taro', 'common']

编译为微信小程序插件时的默认值: ['plugin/runtime', 'plugin/vendors', 'plugin/taro', 'plugin/common']

可以传入需要抽取的公共文件的名称数组。

例子:

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. commonChunks: ['runtime', 'vendors', 'taro', 'common']
  6. }
  7. }

这几个公共文件分别表示:

  • runtime: webpack 运行时入口
  • taro: node_modules 中 Taro 相关依赖
  • vendors: node_modules 除 Taro 外的公共依赖
  • common: 项目中业务代码公共逻辑

函数方式

通过对入参的默认公共文件数组进行操作,返回新的数组来进行配置,如下

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. commonChunks (commonChunks) {
  6. // commonChunks 的取值即为默认的公共文件名数组
  7. commonChunks.push('yourCustomCommonChunkName')
  8. return commonChunks
  9. }
  10. }
  11. }

mini.addChunkPages

function

为某些页面单独指定需要引用的公共文件。

例如在使用小程序分包的时候,为了减少主包大小,分包的页面希望引入自己的公共文件,而不希望直接放在主包内。那么我们首先可以通过 webpackChain 配置 来单独抽离分包的公共文件,然后通过 mini.addChunkPages 为分包页面配置引入分包的公共文件,其使用方式如下:

mini.addChunkPages 配置为一个函数,接受两个参数

  • pages 参数为 Map 类型,用于为页面添加公共文件
  • pagesNames 参数为当前应用的所有页面标识列表,可以通过打印的方式进行查看页面的标识

例如,为 pages/index/index 页面添加 eatingmorning 两个抽离的公共文件:

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. addChunkPages (pages: Map<string, string[]>, pagesNames: string[]) {
  6. pages.set('pages/index/index', ['eating', 'morning'])
  7. }
  8. }
  9. }

mini.optimizeMainPackage

object

优化主包的体积大小

像下面这样简单配置之后,可以避免主包没有引入的module不被提取到commonChunks中,该功能会在打包时分析module和chunk的依赖关系,筛选出主包没有引用到的module把它提取到分包内,下面是提取的两种类型的分包公共模块

  • 分包根目录/sub-vendors.(js|wxss)

    • 如果该module只被单个分包内的多个page引用,则提取到该分包根目录的sub-vendors文件中。
  • 分包根目录/sub-common/*.(js|wxss)

    • 如果该module被多个分包内的page引用,正常情况下会被提取到主包的公共模块中,这里为了保证主包的体积最优,则会先提取成一个公共模块,然后分别复制到对应分包的sub-common文件夹下(因为小程序无法跨分包引入文件,所以这里需要每个分包都复制一份),需要注意的是,这样会导致总包的体积变大一些。
  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. optimizeMainPackage: {
  6. enable: true
  7. }
  8. }
  9. }

如果有不想走分包提取规则的module,可以在exclude中配置,这样该module就会走原来提取的方案,提取到主包中,比如像下面这样(支持绝对路径和函数):

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. optimizeMainPackage: {
  6. enable: true,
  7. exclude: [
  8. path.resolve(__dirname, 'moduleName.js'),
  9. (module) => module.resource.indexOf('moduleName') >= 0
  10. ]
  11. }
  12. }
  13. }

mini.styleLoaderOption

object

style-loader 的附加配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. styleLoaderOption: {
  6. insertAt: 'top'
  7. }
  8. }
  9. }

mini.cssLoaderOption

object

css-loader 的附加配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. cssLoaderOption: {
  6. localIdentName: '[hash:base64]'
  7. }
  8. }
  9. }

mini.sassLoaderOption

object

sass-loader 的附加配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. sassLoaderOption: {
  6. implementation: require("node-sass")
  7. }
  8. }
  9. }

mini.lessLoaderOption

自 v3.0.26 开始支持

object

less-loader 的附加配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. lessLoaderOption: {
  6. lessOptions: {
  7. strictMath: true,
  8. noIeCompat: true
  9. }
  10. }
  11. }
  12. }

mini.stylusLoaderOption

object

stylus-loader 的附加配置。配置项参考官方文档

mini.miniCssExtractPluginOption

object

mini-css-extract-plugin 的附加配置,配置项参考官方文档

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. miniCssExtractPluginOption: {
  6. filename: '[name].css',
  7. chunkFilename: '[name].css'
  8. }
  9. }
  10. }

mini.imageUrlLoaderOption

object

针对 png | jpg | jpeg | gif | bpm | svg 文件的 url-loader 配置。配置项参考官方文档

mini.mediaUrlLoaderOption

object

针对 mp4 | webm | ogg | mp3 | wav | flac | aac 文件的 url-loader 配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. mini: {
  4. // ...
  5. mediaUrlLoaderOption: {
  6. limit: 8192
  7. }
  8. }
  9. }

mini.fontUrlLoaderOption

object

针对 woff | woff2 | eot | ttf | otf 文件的 url-loader 配置。配置项参考官方文档

h5

专属于 H5 的配置。

h5.entry

object

可用于修改、拓展 Webpack 的 input 选项,配置项参考 官方文档

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. entry: {
  6. home: ['./home.js'],
  7. about: ['./about.js'],
  8. contact: ['./contact.js']
  9. }
  10. }
  11. }

h5.output

object

可用于修改、拓展 Webpack 的 output 选项,配置项参考官方文档

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. output: {
  6. filename: 'js/[name].[hash:8].js',
  7. chunkFilename: 'js/[name].[chunkhash:8].js'
  8. }
  9. }
  10. }

h5.publicPath

string

默认值:'/'

设置输出解析文件的目录。

h5.staticDirectory

string

默认值:'static'

h5 编译后的静态文件目录。

h5.chunkDirectory

string

默认值:'chunk'

编译后非 entry 的 js 文件的存放目录,主要影响动态引入的 pages 的存放路径。

h5.devServer

object

预览服务的配置,可以更改端口等参数。具体配置参考 webpack-dev-server

例子:

修改端口:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. devServer: {
  6. port: 10086
  7. }
  8. }
  9. }

开启 https 服务:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. devServer: {
  6. https: true
  7. }
  8. }
  9. }

h5.webpackChain

function

自定义 Webpack 配置。

这个函数会收到两个参数,第一个参数是 webpackChain 对象,可参考 webpack-chain 的 API 进行修改,第二个参数是 webpack 实例。

例子:

  1. // 这是一个添加 raw-loader 的例子,用于在项目中直接引用 md 文件
  2. module.exports = {
  3. // ...
  4. h5: {
  5. // ...
  6. webpackChain (chain, webpack) {
  7. chain.merge({
  8. module: {
  9. rule: {
  10. myloader: {
  11. test: /\.md$/,
  12. use: [{
  13. loader: 'raw-loader',
  14. options: {}
  15. }]
  16. }
  17. }
  18. }
  19. })
  20. }
  21. }
  22. }
  1. // 这是一个添加插件的例子
  2. module.exports = {
  3. // ...
  4. h5: {
  5. // ...
  6. webpackChain (chain, webpack) {
  7. chain.merge({
  8. plugin: {
  9. install: {
  10. plugin: require('npm-install-webpack-plugin'),
  11. args: [{
  12. // Use --save or --save-dev
  13. dev: false,
  14. // Install missing peerDependencies
  15. peerDependencies: true,
  16. // Reduce amount of console logging
  17. quiet: false,
  18. // npm command used inside company, yarn is not supported yet
  19. npm: 'cnpm'
  20. }]
  21. }
  22. }
  23. })
  24. }
  25. }
  26. }

h5.router

object

路由相关的配置。

h5.router.mode

'hash' | 'browser'

默认值:'hash'

配置路由模式。’hash’ 与 ‘browser’ 分别对应 hash 路由模式和浏览器 history 路由模式。

例子:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. router: {
  6. mode: 'hash' // 或者是 'browser'
  7. }
  8. }
  9. }

针对上面的配置,调用 Taro.navigateTo({ url: '/pages/index/index' }) 后,浏览器地址栏将被变为:

  • https://{{domain}}/#/pages/index/indexhash 模式)
  • https://{{domain}}/pages/index/indexbrowser 模式)

h5.router.basename

string

配置路由基准路径。

例子:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. router: {
  6. basename: '/myapp'
  7. }
  8. }
  9. }

针对上面的配置,调用 Taro.navigateTo({ url: '/pages/index/index' }) 后,浏览器地址栏将被变为:

  • https://{{domain}}/#/myapp/pages/index/indexhash 模式)
  • https://{{domain}}/myapp/pages/index/indexbrowser 模式)

h5.router.customRoutes

object

配置自定义路由。

例子:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. router: {
  6. customRoutes: {
  7. '/pages/index/index': '/index'
  8. }
  9. }
  10. }
  11. }

针对上面的配置,调用 Taro.navigateTo({ url: '/pages/index/index' }) 后,浏览器地址栏将被变为:

  • https://{{domain}}/#/indexhash 模式)
  • https://{{domain}}/myapp/indexbrowser 模式)

h5.enableSourceMap

boolean

默认值:watch 模式下为 true,否则为 false

用于控制是否生成 js、css 对应的 sourceMap。

h5.sourceMapType

string

默认值:'cheap-module-eval-source-map'

具体配置请参考 Webpack devtool 配置

h5.useHtmlComponents

Taro 3.2.4 开始支持

boolean

默认值:false

用于控制在 H5 端是否使用兼容性组件库,详情请看 React 兼容性组件库

h5.enableExtract

boolean

默认值:watch 模式下为 false,否则为 true

extract 功能开关,开启后将使用 mini-css-extract-plugin 分离 css 文件,可通过 h5.miniCssExtractPluginOption 对插件进行配置。

h5.esnextModules

array

配置需要额外的经由 Taro 预设的 postcss 编译的模块。

假设需要对 taro-ui 里的样式单位进行转换适配:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. // 经过这一配置之后,代码中引入的处于 `node_modules/taro-ui/` 路径下的样式文件均会经过 postcss 的编译处理。
  6. esnextModules: ['taro-ui']
  7. }
  8. }

h5.postcss

object

配置 postcss 相关插件。

h5.postcss.autoprefixer

object

可以进行 autoprefixer 的配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. postcss: {
  6. autoprefixer: {
  7. enable: true,
  8. config: {
  9. /* autoprefixer 配置项 */
  10. }
  11. }
  12. }
  13. }
  14. }

h5.postcss.pxtransform

object

可以进行 pxtransform 的配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. postcss: {
  6. pxtransform: {
  7. enable: true,
  8. config: {
  9. /* pxtransform 配置项 */
  10. }
  11. }
  12. }
  13. }
  14. }

h5.postcss.cssModules

object

可以进行 CSS Modules 配置,配置如下:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. postcss: {
  6. // css modules 功能开关与相关配置
  7. cssModules: {
  8. enable: false, // 默认为 false,如需使用 css modules 功能,则设为 true
  9. config: {
  10. namingPattern: 'module',
  11. generateScopedName: '[name]__[local]___[hash:base64:5]'
  12. }
  13. }
  14. }
  15. }
  16. }

h5.styleLoaderOption

object

style-loader 的附加配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. styleLoaderOption: {
  6. insertAt: 'top'
  7. }
  8. }
  9. }

h5.cssLoaderOption

object

css-loader 的附加配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. cssLoaderOption: {
  6. localIdentName: '[hash:base64]'
  7. }
  8. }
  9. }

h5.sassLoaderOption

object

sass-loader 的附加配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. sassLoaderOption: {
  6. implementation: require("node-sass")
  7. }
  8. }
  9. }

h5.lessLoaderOption

自 v3.0.26 开始支持

object

less-loader 的附加配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. lessLoaderOption: {
  6. lessOptions: {
  7. strictMath: true,
  8. noIeCompat: true
  9. }
  10. }
  11. }
  12. }

h5.stylusLoaderOption

object

stylus-loader 的附加配置。配置项参考官方文档

h5.miniCssExtractPluginOption

object

mini-css-extract-plugin 的附加配置,在 h5.enableExtract 配置true 的情况下生效。

配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. miniCssExtractPluginOption: {
  6. filename: 'css/[name].css',
  7. chunkFilename: 'css/[id].css'
  8. }
  9. }
  10. }

h5.imageUrlLoaderOption

object

针对 png | jpg | jpeg | gif | bpm | svg 文件的 url-loader 配置。配置项参考官方文档

h5.mediaUrlLoaderOption

object

针对 mp4 | webm | ogg | mp3 | wav | flac | aac 文件的 url-loader 配置。配置项参考官方文档,例如:

  1. module.exports = {
  2. // ...
  3. h5: {
  4. // ...
  5. mediaUrlLoaderOption: {
  6. limit: 8192
  7. }
  8. }
  9. }

h5.fontUrlLoaderOption

object

针对 woff | woff2 | eot | ttf | otf 文件的 url-loader 配置。配置项参考官方文档

rn

专属于 RN 的配置。

rn.appName

string

设置RN bundle中注册应用的名称

  1. module.exports = {
  2. // ...
  3. rn: {
  4. // ...
  5. appName: 'TaroDemo'
  6. }
  7. }

rn.entry

string

entry利用模块查找规则{name}.{platform}.{ext}自动区分平台

  1. module.exports = {
  2. // ...
  3. rn: {
  4. // ...
  5. entry: 'index.android.tsx'
  6. }
  7. }

rn.output

object

设置Metro打包生成bundle的输出路径,默认 dist 目录下

  1. module.exports = {
  2. // ...
  3. rn: {
  4. // ...
  5. output: {
  6. ios: '../taro-native-shell/ios/main.jsbundle',
  7. iosAssetsDest: '../taro-native-shell/ios',
  8. android: '../taro-native-shell/android/app/src/main/assets/index.android.bundle',
  9. androidAssetsDest: '../taro-native-shell/android/app/src/main/res'
  10. },
  11. }
  12. }

rn.postcss

object

postcss 相关配置,其他样式语言预处理后经过此配置。

  1. module.exports = {
  2. // ...
  3. rn: {
  4. // ...
  5. postcss: {
  6. // postcss 配置,参考 https://github.com/postcss/postcss#options
  7. options: { /* ... */ },
  8. // 默认true,控制是否对 css value 进行 scalePx2dp 转换,pxtransform配置 enable 才生效
  9. scalable: boolean,
  10. pxtransform: {
  11. enable: boolean, // 默认true
  12. config: { /* ... */ } // 插件 pxtransform 配置项,参考尺寸章节
  13. },
  14. },
  15. }
  16. }

rn.sass

object

sass 相关配置。options 配置项参考官方文档

  1. module.exports = {
  2. // ...
  3. rn: {
  4. // ...
  5. sass: {
  6. options: { /* ... */ },
  7. // 加入到脚本注入的每个 sass 文件头部,在 config.sass 之前
  8. additionalData: '', // {String|Function}
  9. }
  10. }
  11. }

rn.less

object

less 相关配置。options 配置项参考官方文档

  1. module.exports = {
  2. // ...
  3. rn: {
  4. // ...
  5. less: {
  6. options: { /* ... */ },
  7. additionalData: '', // {String|Function}
  8. }
  9. }
  10. }

rn.stylus

object

stylus 相关配置。stylus.options 配置项参考文档

  1. module.exports = {
  2. // ...
  3. rn: {
  4. // ...
  5. stylus: {
  6. options: { /* ... */ },
  7. additionalData: '', // {String|Function}
  8. }
  9. }
  10. }

rn.resolve

object

resolve 是处理引用文件的配置。下面可以进行 include 配置,处理引用 node_modules 文件的跨平台处理,默认不处理。

  1. module.exports = {
  2. // ...
  3. rn: {
  4. // ...
  5. resolve: {
  6. // ...
  7. include: ['test'] // 处理引用 node_modules/test 文件的跨平台处理。
  8. }
  9. }
  10. }