编译配置详情

sourceRoot ​

string

默认值： 'src'

源码存放目录。

outputRoot ​

string

默认值： 'dist'

代码编译后的生产目录。

designWidth ​

number | function

默认值： 750

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

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

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

defineConstants ​

object

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

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

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 ：

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

config/prod.js ：

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

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

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 ​

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 ​

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 ​

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 ​

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 的退出码结束进程。