designWidth

designWidth 用来设置设计稿尺寸，关于这一部分的配置说明请见设计稿及尺寸单位这一章节。

sourceRoot

sourceRoot 用来设置源码存放目录，通过 Taro 开发工具初始化后的项目源码目录都是 src，你可以通过修改这一配置来重新指定源码目录。

outputRoot

outputRoot 用来设置代码编译后的生产目录，通过 Taro 开发工具初始化后的生产目录都是 dist，你可以通过修改这一配置来重新指定生产目录。

plugins

plugins 用来设置一些各个端通用的编译过程配置，例如 babel 配置，JS/CSS 压缩配置等。

plugins.babel

用来配置 babel，默认配置如下，可以自行添加自己需要的额外的 presets 及 plugins。

  1. babel: {
  2.   sourceMap: true,
  3.   presets: [
  4.     'env'
  5.   ],
  6.   plugins: [
  7.     'transform-class-properties',
  8.     'transform-decorators-legacy',
  9.     'transform-object-rest-spread'
  10.   ]
  11. }

plugins.uglify

用来配置 UgligyJS 工具，设置打包过程中的 JS 代码压缩。可以通过 plugins.uglify.enable 来设置是否开启压缩，若设置开启，则可以通过 plugins.uglify.config 来设置 UgligyJS 的配置项，具体配置方式如下：

  1. uglify: {
  2.   enable: true,
  3.   config: {
  4.     // 配置项同 https://github.com/mishoo/UglifyJS2#minify-options
  5.   }
  6. }

plugins.csso

用来配置 csso 工具，设置打包过程中的 CSS 代码压缩。可以通过 plugins.csso.enable 来设置是否开启压缩，若设置开启，则可以通过 plugins.csso.config 来设置 csso 的配置项，具体配置方式如下：

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

env

用来设置一些环境变量如 process.env.NODE_ENV，例如我们想设置区分预览、打包来做些不同的操作，可以如下配置：

在 config/dev.js 中：

  1. env: {
  2.   NODE_ENV: '"development"' // JSON.stringify('development')
  3. }

在 config/prod.js 中：

  1. env: {
  2.   NODE_ENV: '"production"' // JSON.stringify('production')
  3. }

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

defineConstants

用来配置一些全局变量供代码中进行使用，例如：

  1. defineConstants: {
  2.   A: '"a"' // JSON.stringify('a')
  3. }

alias

1.2.0 开始支持。

用来配置目录别名，从而方便书写代码引用路径。例如，使用相对路径书写文件引用如下：

  1. import A from '../../componnets/A'
  2. import Utils from '../../utils'

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

  1. alias: {
  2.   '@components': path.resolve(__dirname, '..', 'src/components'),
  3.   '@utils': path.resolve(__dirname, '..', 'src/utils')
  4. }

通过上述配置，可以将 src 、src/components 以及 src/utils 目录配置成别名，则代码中的引用改写如下：

  1. import A from '@components/A'
  2. import Utils from '@utils'

copy

文件 copy 配置，包含两个配置项 patterns 和 options。

copy.patterns

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

值得注意的是，目前 from 必须指定存在的文件或者目录，暂不支持 glob 格式， from 和 to 直接置顶项目根目录下的文件目录，建议 from 以 src 目录开头，to 以 dist 目录开头。

一般有如下的使用形式：

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

copy.options

拷贝配置，目前可以指定全局的 ignore：

  1. copy: {
  2.   options: {
  3.     ignore: ['*.js', '*.css'] // 全局的 ignore
  4.   }
  5. }

weapp

专属于小程序的配置。

weapp.compile

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

weapp.compile.compressTemplate

决定小程序打包时是否需要压缩 wxml

weapp.compile.exclude

配置小程序编译过程中排除不需要经过 Taro 编译的文件，数组类型，写文件路径，文件路径必须以源码所在 src 目录开头：

  1. weapp: {
  2.   compile: {
  3.     exclude: ['src/components/ec-canvas/echarts.js']
  4.   }
  5. }

weapp.module

配置一些小程序端用到的插件模块配置，例如 postcss 等。

weapp.module.postcss

配置 postcss 相关插件：

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

h5

专属于 H5 的配置。

h5.devServer

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

  1. devServer: {
  2.   port: 10086
  3. }

默认是http服务，如果想开启https服务需要做如下配置。

  1. devServer: {
  2.   https: true
  3. }

h5.output

输出配置

  1. output: {
  2.   filename: 'js/[name].[hash:8].js',
  3.   chunkFilename: 'js/[name].[chunkhash:8].js'
  4. }

h5.publicPath

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

h5.staticDirectory

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

h5.chunkDirectory

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

h5.webpackChain

自定义 webpack 配置，接受函数形式的配置。

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

  1. /* 这是一个添加 ts-loader 的例子，但事实上 taro 是默认支持 ts 的，并不需要这样做。 */
  2. {
  3.   webpackChain (chain, webpack) {
  4.     chain.merge({
  5.       module: {
  6.         rule: {
  7.           myloader: {
  8.             test: /.tsx?/,
  9.             use: [{
  10.               loader: 'ts-loader',
  11.               options: {}
  12.             }]
  13.           }
  14.         }
  15.       }
  16.     })
  17.   }
  18. }
  1. /* 这是一个添加插件的例子： */
  2. {
  3.   webpackChain (chain, webpack) {
  4.     chain.merge({
  5.       plugin: {
  6.         install: {
  7.           plugin: require('npm-install-webpack-plugin'),
  8.           args: [{
  9.             // Use --save or --save-dev
  10.             dev: false,
  11.             // Install missing peerDependencies
  12.             peerDependencies: true,
  13.             // Reduce amount of console logging
  14.             quiet: false,
  15.             // npm command used inside company, yarn is not supported yet
  16.             npm: 'cnpm'
  17.           }]
  18.         }
  19.       }
  20.     })
  21.   }
  22. }

[DEPRECATED]h5.webpack

自定义 webpack 配置。这个配置项支持两种形式的配置：

  1. 如果该配置项以对象的形态呈现，taro 将会使用 webpack-merge 将这个对象合并到默认的配置项中。 例子：

    1. webpack: {
    2. resolve: {
    3.  alias: {
    4.    'test': './test'
    5.  }
    6. }
    7. }

  2. 如果该配置以函数的形态呈现，那这个函数将会接收到两个参数：默认配置（defaultConfig）和 webpack 实例（webpack）。taro 将会以该函数的返回值作为最终的 webpack 配置。

例子：

  1. webpack (defaultConfig, webpack) {
  2.   defaultConfig.plugins.push(
  3.     new webpack.EnvironmentPlugin(['NODE_ENV'])
  4.   )
  5.   return defaultConfig
  6. }

h5.router

路由相关的配置，支持路由模式、路由基准路径以及自定义路由的配置。

h5.router.mode

路由模式配置。配置值为hash（默认值）或browser，分别对应 hash 路由模式和浏览器 history 路由模式。例子：

  1. h5: {
  2.   /* 其他配置 */
  3.   ... ,
  4.   router: {
  5.     mode: 'hash' // 或者是 "browser"
  6.   }
  7. }

　 针对上面的配置，调用Taro.navigateTo({ url: '/pages/index/index' })后，浏览器地址栏将被变为http://{{domain}}/#/pages/index/index（hash模式）或者http://{{domain}}/pages/index/index（browser模式）。

h5.router.basename

路由基准路径的配置，配置值为string类型。例子：

  1. h5: {
  2.   /* 其他配置 */
  3.   ... ,
  4.   router: {
  5.     basename: '/myapp'
  6.   }
  7. }

针对上面的配置，调用Taro.navigateTo({ url: '/pages/index/index' })后，浏览器地址栏将被变为http://{{domain}}/#/myapp/pages/index/index（hash模式）或者http://{{domain}}/myapp/pages/index/index（browser模式）。

h5.router.customRoutes

自定义路由的配置，配置值为{ [key: string]: string }类型。例子：

  1. h5: {
  2.   /* 其他配置 */
  3.   ... ,
  4.   router: {
  5.     customRoutes: {
  6.       '/pages/index/index': '/index'
  7.     }
  8.   }
  9. }

针对上面的配置，调用Taro.navigateTo({ url: '/pages/index/index' })后，浏览器地址栏将被变为http://{{domain}}/#/index（hash模式）或者http://{{domain}}/myapp/index（browser模式）。

h5.entry

Taro app 的入口，同webpack.entry。

  1. {
  2.   entry: {
  3.     home: './home.js',
  4.     about: './about.js',
  5.     contact: './contact.js'
  6.   }
  7. }

h5.enableSourceMap

sourceMap 开关，影响 js、css 的 sourceMap 配置。 dev 状态默认 开，prod 状态默认 关。

h5.enableDll

dll 开关，开启后将使用dllPlugin把内置的部分依赖库打包为单独的dll文件， 某种程度上可以减少首屏单个文件体积。 dev 状态默认 关，prod 状态默认 开。

h5.dllWebpackChain

同h5.webpackChain，不过作用于dll。

h5.dllEntry

dll编译过程的entry配置项，决定了dll文件的内容，可参考webpack.entry。默认值：

  1. h5: {
  2.   /* 其他配置 */
  3.   ...,
  4.   dllEntry: {
  5.     lib: ['nervjs', '@tarojs/taro-h5', '@tarojs/router', '@tarojs/components']
  6.   }
  7. }

h5.enableExtract

extract 功能开关，开启后将使用mini-css-extract-plugin分离 css 文件， 可通过h5.miniCssExtractPluginOption对插件进行配置。 dev 状态默认 关，prod 状态默认 开。

h5.esnextModules

配置需要额外的编译的源码模块，比如taro-ui：

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

h5.cssLoaderOption

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

  1. {
  2.   cssLoaderOption: {
  3.     localIdentName: '[hash:base64]'
  4.   }
  5. }

h5.styleLoaderOption

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

  1. {
  2.   styleLoaderOption: {
  3.     insertAt: 'top'
  4.   }
  5. }

h5.sassLoaderOption

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

  1. {
  2.   sassLoaderOption: {
  3.     implementation: require("dart-sass")
  4.   }
  5. }

h5.lessLoaderOption

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

  1. {
  2.   lessLoaderOption: {
  3.     strictMath: true,
  4.     noIeCompat: true
  5.   }
  6. }

h5.stylusLoaderOption

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

h5.mediaUrlLoaderOption

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

  1. {
  2.   mediaUrlLoaderOption: {
  3.     limit: 8192
  4.   }
  5. }

h5.fontUrlLoaderOption

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

h5.imageUrlLoaderOption

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

h5.miniCssExtractPluginOption

mini-css-extract-plugin的附加配置，在enableExtract为true的情况下生效。 配置项参考官方文档，例如：

  1. {
  2.   miniCssExtractPluginOption: {
  3.     filename: 'css/[name].css',
  4.     chunkFilename: 'css/[id].css'
  5.   }
  6. }

h5.module

配置一些 H5 端用到的插件模块配置，暂时只有 postcss。

h5.module.postcss.autoprefixer

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

  1. postcss: {
  2.   autoprefixer: {
  3.     enable: true,
  4.     config: {
  5.       /* autoprefixer 配置项 */
  6.     }
  7.   }
  8. }

h5.module.postcss.pxtransform

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

  1. postcss: {
  2.   pxtransform: {
  3.     enable: true,
  4.     config: {
  5.       /* pxtransform 配置项 */
  6.     }
  7.   }
  8. }

h5.module.postcss.cssModules

可以进行 H5 端 css modules 配置，配置如下：

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