编译配置详情

designWidth

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

sourceRoot

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

outputRoot

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

plugins

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

plugins.babel

用来配置 babel,默认配置如下,可以自行添加自己需要的额外的 presetsplugins

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

plugins.sass

用来配置 sass 工具,设置打包过程中的 SCSS 代码编译。具体配置可以参考node-sass当需要全局注入scss文件时,可以添加三个额外参数:resourceprojectDirectory (v1.2.25开始支持)、data(v1.3.0开始支持),具体配置方式如下:

单文件路径形式

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

  1. sass: {
  2. resource: path.resolve(__dirname, '..', 'src/styles/variable.scss')
  3. }

多文件路径形式

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

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

指定项目根目录路径形式

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

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

传入 scss 变量字符串

  1. sass: {
  2. resource: [
  3. 'src/styles/variable.scss',
  4. 'src/styles/mixins.scss'
  5. ],
  6. projectDirectory: path.resolve(__dirname, '..'),
  7. data: '$nav-height: 48px;'
  8. }
  • resource: 如果要引入多个文件,支持数组形式传入
  • projectDirectory: 项目根目录的绝对地址(若为小程序云开发模板,则应该是client目录)
  • data: 全局 scss 变量,若 data 与 resource 中设置了同样的变量,则 data 的优先级高于 resource

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'
  3. import packageJson from '../../package.json'
  4. import projectConfig from '../../project.config.json'

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

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

通过上述配置,可以将 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)产生命名冲突。

copy

文件 copy 配置,包含两个配置项 patternsoptions

copy.patterns

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

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

一般有如下的使用形式:

  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 配置。这个配置项支持两种形式的配置:

  • 如果该配置项以对象的形态呈现,Taro 将会使用 webpack-merge 将这个对象合并到默认的配置项中。例子:
  1. webpack: {
  2. resolve: {
  3. alias: {
  4. 'test': './test'
  5. }
  6. }
  7. }
  • 如果该配置以函数的形态呈现,那这个函数将会接收到两个参数:默认配置(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.sourceMapType

sourceMap格式, 默认cheap-module-eval-source-map。具体配置

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 的附加配置,在 enableExtracttrue 的情况下生效。配置项参考官方文档,例如:

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