版本：4.x

编译配置详情

sourceRoot

string

默认值：'src'

源码存放目录。

outputRoot

string

默认值：'dist'

代码编译后的生产目录。

designWidth

信息

Taro v3.4.13 开始支持传入函数，#11073

number | function

默认值：750

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

当传入函数时，参数是当前样式文件的绝对路径，开发者可以根据不同的文件路径返回对应的 designWidth，例子：

config/index.js
config = {
  designWidth(input) {
    if (input?.file.replace(/\\+/g, '/').indexOf('@nutui/nutui-taro') > -1) {
      return 375
    }
    return 750
  },
}

defineConstants

object

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

配置方式可参考 Webpack DefinePlugin，例如：

/config/index.js
module.exports = {
  // ...
  defineConstants: {
    A: '"a"', // JSON.stringify('a')
  },
}

alias

object

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

例如，使用相对路径书写文件引用如下：

import A from '../../components/A'
import Utils from '../../utils'
import packageJson from '../../package.json'
import projectConfig from '../../project.config.json'

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

module.exports = {
  // ...
  alias: {
    '@/components': path.resolve(__dirname, '..', 'src/components'),
    '@/utils': path.resolve(__dirname, '..', 'src/utils'),
    '@/package': path.resolve(__dirname, '..', 'package.json'),
    '@/project': path.resolve(__dirname, '..', 'project.config.json'),
  },
}

通过上述配置，可以将 src/components 和 src/utils 目录配置成别名，将根目录下的 package.json 和 project.config.json 文件配置成别名，则代码中的引用改写如下：

import A from '@/components/A'
import Utils from '@/utils'
import packageJson from '@/package'
import projectConfig from '@/project'

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

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["./src/components/*"],
      "@/utils/*": ["./src/utils/*"],
      "@/package": ["./package.json"],
      "@/project": ["./project.config.json"]
    }
  }
}

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

env

object

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

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

config/dev.js：

/config/dev.js
module.exports = {
  // ...
  env: {
    NODE_ENV: '"development"', // JSON.stringify('development')
  },
}

config/prod.js：

config/prod.js
module.exports = {
  // ...
  env: {
    NODE_ENV: '"production"', // JSON.stringify('production')
  },
}

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

注意

这里的配置的环境变量只能在 业务代码 中使用，无法在 node环境 代码中获取到其配置的值，也不会改变 node环境 中 process.env.NODE_ENV 的值。配置环境变量更推荐使用模式和环境变量

copy

object

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

copy.patterns

array

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

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

一般有如下的使用形式：

module.exports = {
  // ...
  copy: {
    patterns: [
      { from: 'src/asset/tt/', to: 'dist/asset/tt/', ignore: ['*.js'] }, // 指定需要 copy 的目录
      { from: 'src/asset/tt/sd.jpg', to: 'dist/asset/tt/sd.jpg' }, // 指定需要 copy 的文件
    ],
  },
}

copy.options

object

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

module.exports = {
  // ...
  copy: {
    options: {
      ignore: ['*.js', '*.css'], // 全局的 ignore
    },
  },
}

plugins

array

配置 Taro 插件。

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

module.exports = {
  // ...
  plugins: [
    // 从本地绝对路径引入插件
    '/absulute/path/plugin/filename',
    // 引入 npm 安装的插件
    '@tarojs/plugin-mock',
    ['@tarojs/plugin-mock'],
    ['@tarojs/plugin-mock', {}],
  ],
}

给插件传参：

module.exports = {
  // ...
  plugins: [
    // 引入 npm 安装的插件，并传入插件参数
    [
      '@tarojs/plugin-mock',
      {
        mocks: {
          '/api/user/1': {
            name: 'judy',
            desc: 'Mental guy',
          },
        },
      },
    ],
  ],
}

presets

array

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

module.exports = {
  // ...
  presets: [
    // 引入 npm 安装的插件集
    '@tarojs/preset-sth',
    // 引入 npm 安装的插件集，并传入插件参数
    [
      '@tarojs/plugin-sth',
      {
        arg0: 'xxx',
      },
    ],
    // 从本地绝对路径引入插件集，同样如果需要传入参数也是如上
    '/absulute/path/preset/filename',
  ],
}

jsMinimizer

信息

Taro v3.5 开始支持。

terser | esbuild

默认值 terser

配置 JS 压缩工具。

terser

object

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

terser.enable

boolean

默认值 true

是否开启 JS 代码压缩。

terser.config

object

terser 的具体配置。

module.exports = {
  // ...
  terser: {
    enable: true,
    config: {
      // 配置项同 https://github.com/terser/terser#minify-options
    },
  },
}

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

esbuild

信息

Taro v3.5 开始支持。

object

esbuild.minify

object

当 jsMinimizer 为 esbuild 时适用。配置 esbuild MinifyPlugin 工具以压缩 JS 代码。

esbuild.minify.enable

boolean

默认值 true

是否开启 JS 代码压缩。

esbuild.minify.config

object

esbuild MnifyPlugin 的具体配置。

module.exports = {
  // ...
  esbuild: {
    minify: {
      enable: true,
      config: {
        // 配置项同 https://github.com/privatenumber/esbuild-loader#minifyplugin
        target: 'es5', // target 默认值为 es5
      },
    },
  },
}

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

cssMinimizer

信息

Taro v3.5 开始支持。

csso | esbuild | parcelCss

默认值 csso

配置 CSS 压缩工具。

使用 css-minimizer-webpack-plugin 实现，Taro 内部会根据不同配置值选用不同的压缩工具。建议开发者根据项目实际环境进行选择，可参考 CSS Minification Benchmark。

csso

object

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

csso.enable

boolean

默认值 true

是否开启 CSS 代码压缩。

csso.config

object

csso 的具体配置。

module.exports = {
  // ...
  csso: {
    enable: true,
    config: {
      // 配置项同 https://cssnano.co/docs/what-are-optimisations/
    },
  },
}

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 文件的绝对路径。

module.exports = {
  // ...
  sass: {
    resource: path.resolve(__dirname, '..', 'src/styles/variable.scss'),
  },
}

多文件路径形式

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

module.exports = {
  // ...
  sass: {
    resource: [
      path.resolve(__dirname, '..', 'src/styles/variable.scss'),
      path.resolve(__dirname, '..', 'src/styles/mixins.scss'),
    ],
  },
}

指定项目根目录路径形式

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

module.exports = {
  // ...
  sass: {
    resource: ['src/styles/variable.scss', 'src/styles/mixins.scss'],
    projectDirectory: path.resolve(__dirname, '..'),
  },
}

传入 scss 变量字符串

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

module.exports = {
  // ...
  sass: {
    resource: ['src/styles/variable.scss', 'src/styles/mixins.scss'],
    projectDirectory: path.resolve(__dirname, '..'),
    data: '$nav-height: 48px;',
  },
}

framework

string

使用的开发框架。可选值：react、preact、nerv、vue、vue3。

compiler

信息

Taro v3.5 开始支持。

Taro v4.0.0 开始支持 vite 值。

string | object

默认值：'webpack4'

使用的编译工具。可选值：webpack4、webpack5、vite。

取值也可以是对象，此时可以对针对特定的编译器作额外的配置：

compiler.type

string

使用的编译工具。可选值：webpack4、webpack5、vite。

compiler.errorLevel

number

编译过程中的错误处理级别定义。默认为 0，表示发生严重编译错误时进程会退出。

webpack 编译过程中的错误类型主要如下两类：1、致命的 wepback 错误（配置出错等）2、编译错误（缺失的 module，语法错误等）

0：表示发生“1、致命的 webpack 错误（配置出错等）”情况时，返回非 0 的退出码结束进程。 1：表示发生“1、致命的 wepback 错误（配置出错等）2、编译错误（缺失的 module，语法错误等）”情况时，返回非 0 的退出码结束进程。

compiler.prebundle

object

只有 Webpack5 支持

是否开启依赖预编译功能。开启后首次编译 Taro 会把项目的 node_modules 依赖打包为模块联邦的 Remote 应用，二次编译时 Webpack 只需要编译项目源码，从而提升编译速度。

compiler.prebundle.enable

boolean

默认值：生产环境为 false，开发环境为 true

是否开启依赖预编译。因为使用了 esbuild 单独打包依赖，会使项目体积略微变大，所以生产模式下不建议开启。

compiler.prebundle.cacheDir

string

默认值：[项目路径]/node_modules/.taro

缓存目录的绝对路径。开发者可以自定义缓存目录的路径，并把该目录提交到 git，这样能提高多人协作时的编译速度。

compiler.prebundle.force

boolean

默认值：false

是否强行弃用缓存。

compiler.prebundle.timings

boolean

默认值：false

是否显示依赖预编译的测速信息。

compiler.prebundle.esbuild

object

自定义 esbuild 配置。

compiler.prebundle.swc

object

自定义 swc 配置。

compiler.prebundle.webpack

object

自定义 webpack 配置。

compiler.prebundle.webpack.provide

提供 @tarojs/runtime 替换小程序运行时关联 API（BOM、DOM），使用可参考代码。

compiler.prebundle.include

string array

默认值：[]

需要额外执行预编译的依赖。

compiler.prebundle.exclude

string array

默认值：[]

不需要执行预编译的依赖。

compiler.vitePlugins

只有 vite 支持

array

vite 插件

cache

信息

Taro v3.5 开始支持。

Webpack5 持久化缓存配置。具体配置请参考 WebpackConfig.cache。

Taro 遵循 Webpack “构建安全比构建速度重要”的理念，默认不开启持久化缓存功能。但当开发者能处理好缓存策略时，强烈建议开启缓存，这能大大提高二次编译速度。

除了 cache.buildDependencies、cache.name 具有默认值外，开发者的其它 cache 配置将会合并进 WebpackConfig.cache。

cache.enable

boolean

默认值 false

是否开启持久化缓存。

值为 false 时：开发模式下 WebpackConfig.cache.type = 'memory'，而生产模式下 WebpackConfig.cache = false。

值为 true 时：开发模式和生产模式下均为 WebpackConfig.cache.type = 'filesystem'。

cache.buildDependencies

默认值

webpackConfig = {
  cache: {
    buildDependencies: {
      config: [path.join(appPath, 'config/index.js')],
    },
  },
}

当依赖的文件或该文件的依赖改变时，使缓存失效。详情请参考 WebpackConfig.cache.buildDependencies。

cache.name

string

默认值 process.env.NODE_ENV-process.env.TARO_ENV。

缓存子目录的名称。详情请参考 WebpackConfig.cache.name。

logger

信息

Taro v3.5 开始支持。目前只在 Webpack5 compiler 中支持。

控制 Taro 编译日志的输出方式。

quiet

boolean

默认值 true。

是否简化输出日志。

stats

boolean

默认值 false。

是否输出 Webpack Stats 信息。

mini

object

专属于小程序的配置。

mini.baseLevel

number

默认值：16

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

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

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

mini.compile

object

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

mini.compile.exclude

array

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

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

module.exports = {
  // ...
  mini: {
    // ...
    compile: {
      exclude: [path.resolve(__dirname, '..', 'src/pages/index/vod-wx-sdk-v2.js')],
    },
  },
}

也可以配置判断函数：

module.exports = {
  // ...
  mini: {
    // ...
    compile: {
      exclude: [(modulePath) => modulePath.indexOf('vod-wx-sdk-v2') >= 0],
    },
  },
}

mini.compile.include

array

配置额外需要经过 Taro 编译的文件，使用方式与 mini.compile.exclude 一致，同 Rule.include。例如 Taro 默认不编译 node_modules 中的文件，可以通过这个配置让 Taro 编译 node_modules 中的文件。

默认值包括 Taro 项目源码目录 src 以及 Taro 相关的 node_modules。如需将 Taro 项目作为 monorepo 项目的子包，则要自行配置 include 以编译其他子包的文件，示例：

config/index.js
export default {
  // ...
  mini: {
    // ...
    compile: {
      include: [path.resolve(__dirname, '../../package')],
    },
  },
  h5: {
    // ...
    compile: {
      include: [path.resolve(__dirname, '../../package')],
    },
  },
}

mini.webpackChain

function

自定义 Webpack 配置。

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

第三个参数的取值如下：

export enum PARSE_AST_TYPE {
  ENTRY = 'ENTRY',
  PAGE = 'PAGE',
  COMPONENT = 'COMPONENT',
  NORMAL = 'NORMAL',
  STATIC = 'STATIC',
}

例子：

// 这是一个添加 raw-loader 的例子，用于在项目中直接引用 md 文件
module.exports = {
  // ...
  mini: {
    // ...
    webpackChain(chain, webpack) {
      chain.merge({
        module: {
          rule: {
            myloader: {
              test: /\.md$/,
              use: [
                {
                  loader: 'raw-loader',
                  options: {},
                },
              ],
            },
          },
        },
      })
    },
  },
}

// 这是一个添加插件的例子
module.exports = {
  // ...
  mini: {
    // ...
    webpackChain(chain, webpack) {
      chain.merge({
        plugin: {
          install: {
            plugin: require('npm-install-webpack-plugin'),
            args: [
              {
                // Use --save or --save-dev
                dev: false,
                // Install missing peerDependencies
                peerDependencies: true,
                // Reduce amount of console logging
                quiet: false,
                // npm command used inside company
                npm: 'cnpm',
              },
            ],
          },
        },
      })
    },
  },
}

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

信息

Taro v3.0.8 开始支持。

boolean

默认值：false。

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

mini.hot

信息

Taro v3.4.0 开始支持。

boolean

默认值：false。

是否注入兼容微信小程序热重载的代码。详情：#10722

mini.minifyXML

信息

Taro v3.0.8 开始支持。

object

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

mini.minifyXML.collapseWhitespace

boolean

默认值：false。

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

mini.postcss

object

配置 postcss 相关插件。

module.exports = {
  // ...
  mini: {
    // ...
    postcss: {
      // 可以进行 autoprefixer 的配置。配置项参考官方文档 https://github.com/postcss/autoprefixer
      autoprefixer: {
        enable: true,
        config: {
          // autoprefixer 配置项
        },
      },
      pxtransform: {
        enable: true,
        config: {
          // pxtransform 配置项，参考尺寸章节
          selectorBlackList: ['body'],
        },
      },
      // 小程序端样式引用本地资源内联 该属性在 v4.0.0 版本已废弃，小程序端默认全部转换
      // url: {
      //   enable: true,
      //   config: {
      //     maxSize: 10, // 设定转换尺寸上限（单位：kbytes）
      //   },
      // },
      // css modules 功能开关与相关配置
      cssModules: {
        enable: false, // 默认为 false，如需使用 css modules 功能，则设为 true
        config: {
          generateScopedName: '[name]__[local]___[hash:base64:5]',
        },
      },
    },
  },
}

mini.postcss.htmltransform

object

可以进行 htmltransform 的配置。例如：

module.exports = {
  // ...
  mini: {
    // ...
    postcss: {
      htmltransform: {
        enable: false, // 小程序默认关闭该配置
        config: {
          removeCursorStyle: true, // 默认为 true
        },
      },
    },
  },
}

mini.postcss.url

object

可以进行 url 的配置，默认是 inline 配置（config 配置可参考 postcss-url）。例如：

module.exports = {
  // ...
  mini: {
    // ...
    postcss: {
      url: {
        enable: true,
        config: {
          maxSize: 10, // 设定转换尺寸上限（单位 kbytes）
        },
      },
    },
  },
}

mini.commonChunks

array | function

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

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

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

字符串数组方式

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

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

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

例子：

module.exports = {
  // ...
  mini: {
    // ...
    commonChunks: ['runtime', 'vendors', 'taro', 'common'],
  },
}

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

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

函数方式

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

module.exports = {
  // ...
  mini: {
    // ...
    commonChunks(commonChunks) {
      // commonChunks 的取值即为默认的公共文件名数组
      commonChunks.push('yourCustomCommonChunkName')
      return commonChunks
    },
  },
}

mini.addChunkPages

function

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

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

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

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

例如，为 pages/index/index 页面添加 eating 和 morning 两个抽离的公共文件：

module.exports = {
  // ...
  mini: {
    // ...
    addChunkPages(pages: Map<string, string[]>, pagesNames: string[]) {
      pages.set('pages/index/index', ['eating', 'morning'])
    },
  },
}

mini.optimizeMainPackage

object

优化主包的体积大小

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

分包根目录/sub-vendors.(js|wxss)
- 如果该 module 只被单个分包内的多个 page 引用，则提取到该分包根目录的 sub-vendors 文件中。
分包根目录/sub-common/*.(js|wxss)
- 如果该 module 被多个分包内的 page 引用，正常情况下会被提取到主包的公共模块中，这里为了保证主包的体积最优，则会先提取成一个公共模块，然后分别复制到对应分包的 sub-common 文件夹下（因为小程序无法跨分包引入文件，所以这里需要每个分包都复制一份），需要注意的是，这样会导致总包的体积变大一些。

module.exports = {
  // ...
  mini: {
    // ...
    optimizeMainPackage: {
      enable: true,
    },
  },
}

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

module.exports = {
  // ...
  mini: {
    // ...
    optimizeMainPackage: {
      enable: true,
      exclude: [path.resolve(__dirname, 'moduleName.js'), (module) => module.resource.indexOf('moduleName') >= 0],
    },
  },
}

mini.styleLoaderOption

object

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

module.exports = {
  // ...
  mini: {
    // ...
    styleLoaderOption: {
      insertAt: 'top',
    },
  },
}

mini.cssLoaderOption

object

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

module.exports = {
  // ...
  mini: {
    // ...
    cssLoaderOption: {
      localIdentName: '[hash:base64]',
    },
  },
}

mini.sassLoaderOption

object

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

module.exports = {
  // ...
  mini: {
    // ...
    sassLoaderOption: {
      implementation: require('node-sass'),
    },
  },
}

mini.lessLoaderOption

信息

Taro v3.0.26 开始支持。

object

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

module.exports = {
  // ...
  mini: {
    // ...
    lessLoaderOption: {
      lessOptions: {
        strictMath: true,
        noIeCompat: true,
      },
    },
  },
}

mini.stylusLoaderOption

object

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

mini.miniCssExtractPluginOption

object

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

module.exports = {
  // ...
  mini: {
    // ...
    miniCssExtractPluginOption: {
      filename: '[name].css',
      chunkFilename: '[name].css',
    },
  },
}

mini.imageUrlLoaderOption

object

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

mini.mediaUrlLoaderOption

object

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

module.exports = {
  // ...
  mini: {
    // ...
    mediaUrlLoaderOption: {
      limit: 8192,
    },
  },
}

mini.fontUrlLoaderOption

object

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

h5

专属于 H5 的配置。

h5.entry

object

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

module.exports = {
  // ...
  h5: {
    // ...
    entry: {
      home: ['./home.js'],
      about: ['./about.js'],
      contact: ['./contact.js'],
    },
  },
}

h5.output

object

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

vite 编译环境下用于修改、扩展 rollup 的 output，目前仅适配 chunkFileNames 和 assetFileNames 两个配置，修改其他配置请使用 vite 插件进行修改。配置想参考官方文档

module.exports = {
  // ...
  h5: {
    // ...
    output: {
      filename: 'js/[name].[hash:8].js',
      chunkFilename: 'js/[name].[chunkhash:8].js',
    },
  },
}

h5.publicPath

string

默认值：'/'

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

h5.staticDirectory

string

默认值：'static'

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

h5.chunkDirectory

string

默认值：'chunk'

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

h5.devServer

object

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

例子：

修改端口：

module.exports = {
  // ...
  h5: {
    // ...
    devServer: {
      port: 10086,
    },
  },
}

开启 https 服务：

module.exports = {
  // ...
  h5: {
    // ...
    devServer: {
      https: true,
    },
  },
}

h5.webpackChain

function

自定义 Webpack 配置。

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

例子：

// 这是一个添加 raw-loader 的例子，用于在项目中直接引用 md 文件
module.exports = {
  // ...
  h5: {
    // ...
    webpackChain(chain, webpack) {
      chain.merge({
        module: {
          rule: {
            myloader: {
              test: /\.md$/,
              use: [
                {
                  loader: 'raw-loader',
                  options: {},
                },
              ],
            },
          },
        },
      })
    },
  },
}

// 这是一个添加插件的例子
module.exports = {
  // ...
  h5: {
    // ...
    webpackChain(chain, webpack) {
      chain.merge({
        plugin: {
          install: {
            plugin: require('npm-install-webpack-plugin'),
            args: [
              {
                // Use --save or --save-dev
                dev: false,
                // Install missing peerDependencies
                peerDependencies: true,
                // Reduce amount of console logging
                quiet: false,
                // npm command used inside company
                npm: 'cnpm',
              },
            ],
          },
        },
      })
    },
  },
}

h5.router

object

路由相关的配置。

h5.router.mode

'hash' | 'browser' | 'multi'

默认值：'hash'

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

例子：

module.exports = {
  // ...
  h5: {
    // ...
    router: {
      mode: 'hash', // 或者是 'browser'
    },
  },
}

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

https://{{domain}}/#/pages/index/index（hash 模式）
https://{{domain}}/pages/index/index（browser 模式）

'multi' 对应多页面应用路由模式，需要注意的是很多小程序的组件或 API 都是基于 SPA 设计使用的，在 MPA 模式下并不适用，所以使用该模式可能会导致以下隐患：

TabBar 会多次加载，且不支持路由动画
App 生命周期会多次触发（暂未修复），onPageNotFound 事件不支持
生产环境需要额外配置路由映射（根目录跳转、404 页面……）
getCurrentPages 等相关方法不支持

h5.router.basename

string

配置路由基准路径。

例子：

module.exports = {
  // ...
  h5: {
    // ...
    router: {
      basename: '/myapp',
    },
  },
}

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

https://{{domain}}/#/myapp/pages/index/index（hash 模式）
https://{{domain}}/myapp/pages/index/index（browser 模式）

h5.router.customRoutes

Record<string, string | string[]>

配置自定义路由。

例子：

module.exports = {
  // ...
  h5: {
    // ...
    router: {
      customRoutes: {
        // "页面路径": "自定义路由"
        '/pages/index/index': '/index',
        '/pages/detail/index': ['/detail'], // 可以通过数组为页面配置多个自定义路由
      },
    },
  },
}

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

https://{{domain}}/#/index（hash 模式）
https://{{domain}}/myapp/index（browser 模式）

信息

Taro v3.3.18+ 开始支持传入数组配置自定义路由。

配置自定义路由会导致原路由失效（无法访问，但不影响 API 使用），如果需要启用原路由可以参考如下配置:

customRoutes: {
  '/pages/detail/index': ['/detail', '/pages/detail/index']
}

原路由失效会导致开发环境中，首次打开页面错误；如果自定义路由配置为 '/' 则会导致跳转错误，可以通过配置 entryPagePath 修复该问题，3.5.2+ 版本可忽略该问题。

h5.enableSourceMap

boolean

默认值：watch 模式下为 true，否则为 false。

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

h5.sourceMapType

string

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

具体配置请参考 Webpack devtool 配置。

h5.useHtmlComponents

信息

Taro v3.2.4 开始支持。

boolean

默认值：false

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

h5.useDeprecatedAdapterComponent

信息

Taro v3.6.3 开始支持。

boolean

默认值：false

用于控制在 H5 端是否使用旧版本适配器，旧版本采用全局注册组件，懒加载组件相关依赖；新版本适配器会自动注册相关组件，不再需要引入 @tarojs/components/loader 中的全局 defineCustomElements 方法。

h5.enableExtract

boolean

默认值：watch 模式下为 false，否则为 true。

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

h5.esnextModules

array

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

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

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

h5.postcss

object

配置 postcss 相关插件。

h5.postcss.autoprefixer

object

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

module.exports = {
  // ...
  h5: {
    // ...
    postcss: {
      autoprefixer: {
        enable: true,
        config: {
          /* autoprefixer 配置项 */
        },
      },
    },
  },
}

h5.postcss.pxtransform

object

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

module.exports = {
  // ...
  h5: {
    // ...
    postcss: {
      pxtransform: {
        enable: true,
        config: {
          /* pxtransform 配置项 */
        },
      },
    },
  },
}

h5.postcss.htmltransform

object

可以进行 htmltransform 的配置。例如：

module.exports = {
  // ...
  h5: {
    // ...
    postcss: {
      htmltransform: {
        enable: true, // H5 默认开启该配置
        config: {
          removeCursorStyle: false, // 默认为 false
        },
      },
    },
  },
}

需要 v3.5 以上版本

h5.postcss.url

object

可以进行 url 的配置，默认 inline 配置（config 配置可参考 postcss-url）。例如：

module.exports = {
  // ...
  h5: {
    // ...
    postcss: {
      url: {
        enable: true,
        config: {
          maxSize: 10, // 设定转换尺寸上限（单位 kbytes）
        },
      },
    },
  },
}

h5.postcss.cssModules

object

可以进行 CSS Modules 配置，配置如下：

module.exports = {
  // ...
  h5: {
    // ...
    postcss: {
      // css modules 功能开关与相关配置
      cssModules: {
        enable: false, // 默认为 false，如需使用 css modules 功能，则设为 true
        config: {
          namingPattern: 'module',
          generateScopedName: '[name]__[local]___[hash:base64:5]',
        },
      },
    },
  },
}

h5.compile

object

Web 编译过程的相关配置。

需要 v3.6 以上版本

h5.compile.exclude

array

配置 Web 应用编译过程中排除不需要经过 Taro 编译的文件，使用方式与 mini.compile.exclude 一致，同 Rule.exclude。

h5.compile.include

array

config/index.js
export default {
  // ...
  mini: {
    // ...
    compile: {
      include: [path.resolve(__dirname, '../../package')],
    },
  },
  h5: {
    // ...
    compile: {
      include: [path.resolve(__dirname, '../../package')],
    },
  },
}

h5.htmlPluginOption

信息

Taro v3.5 开始支持。

object

html-webpack-plugin 的具体配置。

module.exports = {
  // ...
  htmlPluginOption: {
    // 配置项同 https://github.com/jantimon/html-webpack-plugin#options
  },
}

h5.styleLoaderOption

object

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

module.exports = {
  // ...
  h5: {
    // ...
    styleLoaderOption: {
      insertAt: 'top',
    },
  },
}

h5.cssLoaderOption

object

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

module.exports = {
  // ...
  h5: {
    // ...
    cssLoaderOption: {
      localIdentName: '[hash:base64]',
    },
  },
}

h5.sassLoaderOption

object

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

module.exports = {
  // ...
  h5: {
    // ...
    sassLoaderOption: {
      implementation: require('node-sass'),
    },
  },
}

h5.lessLoaderOption

信息

Taro v3.0.26 开始支持。

object

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

module.exports = {
  // ...
  h5: {
    // ...
    lessLoaderOption: {
      lessOptions: {
        strictMath: true,
        noIeCompat: true,
      },
    },
  },
}

h5.stylusLoaderOption

object

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

h5.miniCssExtractPluginOption

object

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

配置项参考官方文档，例如：

module.exports = {
  // ...
  h5: {
    // ...
    miniCssExtractPluginOption: {
      filename: 'css/[name].css',
      chunkFilename: 'css/[id].css',
    },
  },
}

h5.imageUrlLoaderOption

object

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

h5.mediaUrlLoaderOption

object

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

module.exports = {
  // ...
  h5: {
    // ...
    mediaUrlLoaderOption: {
      limit: 8192,
    },
  },
}

h5.fontUrlLoaderOption

object

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

h5.legacy

信息

Taro v4.0.0 开始支持。

boolean

默认值 false

选择 vite 编译器的情况下才会使用到该字段。生成的代码是否要兼容旧版浏览器，值为 true 时，会去读取 package.json 的 browserslist 字段。

rn

专属于 RN 的配置。

rn.appName

string

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

module.exports = {
  // ...
  rn: {
    // ...
    appName: 'TaroDemo',
  },
}

rn.entry

string

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

module.exports = {
  // ...
  rn: {
    // ...
    entry: 'index.android.tsx',
  },
}

rn.output

object

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

module.exports = {
  // ...
  rn: {
    // ...
    output: {
      iosSourceMapUrl: '', // sourcemap 文件url
      iosSourcemapOutput: '../taro-native-shell/ios/main.map', // sourcemap 文件输出路径
      iosSourcemapSourcesRoot: '', // 将 sourcemap 资源路径转为相对路径时的根目录
      androidSourceMapUrl: '',
      androidSourcemapOutput: '../taro-native-shell/android/app/src/main/assets/index.android.map',
      androidSourcemapSourcesRoot: '',
      ios: '../taro-native-shell/ios/main.jsbundle',
      iosAssetsDest: '../taro-native-shell/ios',
      android: '../taro-native-shell/android/app/src/main/assets/index.android.bundle',
      androidAssetsDest: '../taro-native-shell/android/app/src/main/res',
    },
  },
}

rn.postcss

object

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

module.exports = {
  // ...
  rn: {
    // ...
    postcss: {
      // postcss 配置，参考 https://github.com/postcss/postcss#options
      options: {
        /* ... */
      },
      // 默认true，控制是否对 css value 进行 scalePx2dp 转换，pxtransform配置 enable 才生效
      scalable: boolean,
      pxtransform: {
        enable: boolean, // 默认true
        config: {
          /* ... */
        }, // 插件 pxtransform 配置项，参考尺寸章节
      },
    },
  },
}

rn.sass

object

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

module.exports = {
  // ...
  rn: {
    // ...
    sass: {
      options: {
        /* ... */
      },
      // 加入到脚本注入的每个 sass 文件头部，在 config.sass 之前
      additionalData: '', // {String|Function}
    },
  },
}

rn.less

object

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

module.exports = {
  // ...
  rn: {
    // ...
    less: {
      options: {
        /* ... */
      },
      additionalData: '', // {String|Function}
    },
  },
}

rn.stylus

object

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

module.exports = {
  // ...
  rn: {
    // ...
    stylus: {
      options: {
        /* ... */
      },
      additionalData: '', // {String|Function}
    },
  },
}

rn.resolve

object

resolve 处理依赖文件配置。 resolve.include 可配置多个 npm 包名的数组，将 npm 包当作项目文件处理，支持 node_modules 平台优先级文件访问和全局样式。

module.exports = {
  rn: {
    resolve: {
      include: ['taro-ui'], // 处理引用 node_modules/taro-ui 的依赖。
    },
  },
}

rn.enableMultipleClassName

boolean

支持多 className 转换，以 classname 或 style 结尾的，提取前缀，然后根据前缀，再生成对应的 xxxStyle。如：barClassName -> barStyle。默认值 false，不开启。

module.exports = {
  rn: {
    enableMultipleClassName: false,
  },
}

rn.enableMergeStyle

boolean

当标签 style 属性值是数组时转换成对象。默认值 false，不开启。

module.exports = {
  rn: {
    enableMergeStyle: false, // https://github.com/shinken008/babel-plugin-jsx-attributes-array-to-object#example
  },
}

rn.enableSvgTransform

boolean

将 svg 文件转换为组件引入。默认值 false，不开启。详情：#10793

module.exports = {
  rn: {
    enableSvgTransform: false,
  },
}

sourceRoot​

outputRoot​

designWidth​

defineConstants​

alias​

env​

copy​

copy.patterns​

copy.options​

plugins​

presets​

jsMinimizer​

terser​

terser.enable​

terser.config​

esbuild​

esbuild.minify​

esbuild.minify.enable​

esbuild.minify.config​

cssMinimizer​

csso​

csso.enable​

csso.config​

sass​

sass.resource​

sass.projectDirectory​

sass.data​

全局注入 scss 的例子​

单文件路径形式​

多文件路径形式​

指定项目根目录路径形式​

传入 scss 变量字符串​

framework​

compiler​

compiler.type​

compiler.errorLevel​

compiler.prebundle​

compiler.prebundle.enable​

compiler.prebundle.cacheDir​

compiler.prebundle.force​

compiler.prebundle.timings​

compiler.prebundle.esbuild​

compiler.prebundle.swc​

compiler.prebundle.webpack​

compiler.prebundle.webpack.provide​

compiler.prebundle.include​

compiler.prebundle.exclude​

compiler.vitePlugins​

cache​

cache.enable​

cache.buildDependencies​

cache.name​

logger​

quiet​

stats​

mini​

mini.baseLevel​

mini.compile​

mini.compile.exclude​

mini.compile.include​

mini.webpackChain​

mini.output​

mini.enableSourceMap​

mini.sourceMapType​

mini.debugReact​

mini.hot​

mini.minifyXML​

mini.minifyXML.collapseWhitespace​

mini.postcss​

mini.postcss.htmltransform​

mini.postcss.url​

mini.commonChunks​

字符串数组方式​

函数方式​

mini.addChunkPages​

mini.optimizeMainPackage​

mini.styleLoaderOption​

mini.cssLoaderOption​

mini.sassLoaderOption​

mini.lessLoaderOption​

sourceRoot

outputRoot

designWidth

defineConstants

alias

env

copy

copy.patterns

copy.options

plugins

presets

jsMinimizer

terser

terser.enable

terser.config

esbuild

esbuild.minify

esbuild.minify.enable

esbuild.minify.config

cssMinimizer

csso

csso.enable

csso.config

sass

sass.resource

sass.projectDirectory

sass.data

全局注入 scss 的例子

单文件路径形式

多文件路径形式

指定项目根目录路径形式

传入 scss 变量字符串

framework

compiler

compiler.type

compiler.errorLevel

compiler.prebundle

compiler.prebundle.enable

compiler.prebundle.cacheDir

compiler.prebundle.force

compiler.prebundle.timings

compiler.prebundle.esbuild

compiler.prebundle.swc

compiler.prebundle.webpack

compiler.prebundle.webpack.provide

compiler.prebundle.include

compiler.prebundle.exclude

compiler.vitePlugins

cache

cache.enable

cache.buildDependencies

cache.name

logger

quiet

stats

mini

mini.baseLevel

mini.compile

mini.compile.exclude

mini.compile.include

mini.webpackChain

mini.output

mini.enableSourceMap

mini.sourceMapType

mini.debugReact

mini.hot

mini.minifyXML

mini.minifyXML.collapseWhitespace

mini.postcss

mini.postcss.htmltransform

mini.postcss.url

mini.commonChunks

字符串数组方式

函数方式

mini.addChunkPages

mini.optimizeMainPackage

mini.styleLoaderOption

mini.cssLoaderOption

mini.sassLoaderOption

mini.lessLoaderOption