配置

如何配置

在项目的根目录下创建一个 mako.config.json 文件，并在其中编写配置。

例如：

{
  "entry": {
    "index": "./src/index.js"
  }
}

注意：当你在使用 Mako 与 Umi 时，建议在 .umirc.ts 或 config/config.ts 文件中配置打包工具。

配置项

analyze

是否分析构建产物。

注意：此配置项仍在开发中，结果可能不准确。

autoCSSModules

是否自动启用 CSS Modules。

如果未启用，只有 .module.css 或 .module.less 的文件会被视为 CSS Modules；如果启用，像 import styles from './a.css' 这样的命名导入也会被视为 CSS Modules。

clean

是否在构建前清理输出目录。

cjs

是否输出 cjs 格式代码。

codeSplitting

指定代码拆分策略。对于 SPA 使用 auto 或 granular 策略，对于 MPA 使用 advance 策略。

// auto 策略
{
  codeSplitting: {
    strategy: "auto";
  }
}

// granular 策略
{
  codeSplitting:  {
    strategy: "granular",
    options: {
      // 将被拆分到框架 chunk 的 Node 模块
      frameworkPackages: [ "react", "antd" ],
      // （可选）被拆分的 node 模块的最小大小
      libMinSize: 160000
    }
  }
}


// advance 策略
{
  codeSplitting: {
    strategy: "advanced",
    options: {
      //（可选）拆分 chunk 的最小大小，小于此大小的异步 chunks 将被合并到入口 chunk
      minSize: 20000,
      // 拆分 chunk 分组配置
      groups: [
        {
          // 分组的名称，当前只支持字符串值
          name: "common",
          //（可选）分组包含模块所属的 chunk 类型，枚举值为 "async"（默认）| "entry" | "all"
          allowChunks: "entry",
          //（可选）分组包含的模块的最小引用次数
          minChunks: 1,
          //（可选）分组生效的最小大小
          minSize: 20000,
          //（可选）分组的最大大小，超过此大小将自动再次拆分
          maxSize: 5000000,
          //（可选）分组的匹配优先级，值越大优先级越高
          priority: 0,
          //（可选）分组的匹配正则表达式
          test: "(?:)",
        }
      ],
    },
  }
}

copy

指定需要复制的文件或目录。默认情况下，会将 public 目录下的文件复制到输出目录。

cssModulesExportOnlyLocales

是否只导出 CSS 模块的类名，而不是 CSS 模块的值。通常用于服务端渲染场景，因为在服务端渲染时，你不需要 CSS 模块的值，只需要类名。

define

指定需要在代码中替换的变量。

例如：

{
  define: {
    "FOO": "foo",
  },
}

注意：当前，define 将自动处理 process.env 前缀。

devServer

指定开发服务器的配置。

devtool

指定源映射类型。

duplicatePackageChecker

重复包检查器的配置。

子配置项：

示例：

{
  "duplicatePackageChecker": {
    "verbose": true,
    "showHelp": true,
    "emitError": false
  }
}

dynamicImportToRequire

是否将动态导入转换为 require。在使用 node 平台或希望只有一个 js 输出文件时有用。

例如：

import("./a.js");
// => require("./a.js")

emitAssets

是否输出资产文件。在构建纯服务端渲染项目时，通常设置为 false，因为此时不需要资产文件。

emitDecoratorMetadata

是否输出 decorator metadata。

emotion

是否启用 emotion 支持。

entry

指定入口文件。

例如：

{
  entry: {
    index: "./src/index.js",
    login: "./src/login.js",
  },
}

experimental.detectLoop

生成依赖循环信息的实验配置。设置为 false 可禁用此功能。

配置项：

e.g.

{
  "experimental": {
    "ignoreNodeModules": false,
    "graphviz": true
  }
}

experimental.requireContext

实验性配置，用于启用或禁用 require.context 功能。

e.g.

{
  "experimental": {
    "requireContext": false
  }
}

experimental.webpackSyntaxValidate

实验性配置，指定允许使用 webpack 语法的包。

例如：

{
  experimental: {
    webpackSyntaxValidate: ["foo", "bar"],
  },
}

experimental.magicComment

实验性配置，是否支持通过类似 webpack 的魔法注释。

e.g.

{
  experimental: {
    magicComment: true,
  },
}

魔法注释如下：

import(/* makoChunkName: 'myChunk' */  "./lazy");
import(/* webpackChunkName: 'myChunk' */  "./lazy");
new Worker(/* makoChunkName: 'myWorker' */  new URL("./worker", import.meta.url));
new Worker(/* webpackChunkName: 'myWorker' */  new URL("./worker", import.meta.url));
import(/* makoIgnore: true */ "./foo");
import(/* webpackIgnore: true */ "./foo");

externals

指定外部依赖的配置。

例如：

{
  externals: {
    react: "React",
    "react-dom": "ReactDOM",
  },
}

那么，当代码遇到 import React from "react" 时，它将被替换为 const React = (typeof globalThis !== 'undefined' ? globalThis : self).React。

如果你想要以 require 的方式输出外部依赖，可以如下设置。

{
  externals: {
    foo: "commonjs foo",
  },
}

那么，当代码遇到 import foo from "foo" 时，它将被替换为 const foo = require("foo")。

flexBugs

是否修复 flexbugs。

forkTsChecker

是否在单独的进程上运行 TypeScript 类型检查器。

hash

是否生成哈希文件名。

hmr

是否启用热更新。

ignoreCSSParserErrors

是否忽略 CSS 解析错误。

ignores

指定要忽略的文件。被忽略的文件将输出空模块。

例如：

{
  "ignores": [
    "^assert$",
    "xxxx.provider.js$",
    "^(node:)?({})(/|$)"
  ]
}

inlineCSS

是否将 CSS 内联输出到 JS 中。

注意：此配置仅可与 umd 一起使用，因为注入 CSS 不是推荐的方式，可能会有潜在的性能问题。

inlineLimit

指定需要转换为 base64 格式的资产文件的大小限制。

inlineExcludesExtensions

指定不需要转换为 base64 格式的资产文件的后缀名列表。

例如：

{
  "inlineExcludesExtensions": ["webp"]
}

less

指定 less 配置。

例如。

{
  modifyVars: {
    'primary-color': '#1DA57A',
    'link-color': '#1DA57A',
  },
  globalVars: {
    'primary-color': '#ffff00',
    hack: 'true; @import "your-global-less-file.less";',
  },
  sourceMap: {
    sourceMapFileInline: true,
    outputSourceFiles: true,
  },
  math: 'always',
  plugins: [
    [require.resolve("less-plugin-clean-css"), { roundingPrecision: 1 }]
  ],
}

manifest

是否生成 manifest.json 文件。启用时，默认的 fileName 值为 asset-manifest.json。

mdx

是否启用 mdx 支持。

minify

是否压缩代码。

mode

指定构建模式，"development" 或 "production"。

moduleIdStrategy

指定生成 moduleId 的策略。

nodePolyfill

是否启用 node polyfill。

output

输出相关配置。

optimization

指定用于优化构建产物的配置。当前支持以下子配置项。

platform

指定构建的平台，"browser" 或 "node"。

注意：使用 "node" 时，还需要将 dynamicImportToRequire 设置为 true，因为运行时还不支持 node 风格的块加载。

plugins

指定使用的插件。

// JSHooks
{
  name?: string;
  enforce?: "pre" | "post";
  buildStart?: () => void;
  buildEnd?: () => void;
  generateEnd?: (data: {
    isFirstCompile: boolean;
    time: number;
    stats: {
      startTime: number;
      endTime: number;
      ...
    };
  }) => void;
  writeBundle?: () => void;
  watchChanges?: (id: string, params: { event: "create" | "delete" | "update" }) => void;
  load?: (filePath: string) => Promise<{ content: string, type: 'css'|'js'|'jsx'|'ts'|'tsx' }>;
  loadInclude?: (filePath: string) => boolean;
  resolveId?: (id: string, importer: string, { isEntry: bool }) => Promise<{ id: string, external: bool }>;
  transform?: (content: string, id: string) => Promise<{ content: string, type: 'css'|'js'|'jsx'|'ts'|'tsx' }>;
  transformInclude?: (filePath: string) => Promise<boolean> | boolean;
}

JSHooks 是一组用来扩展 Mako 编译过程的钩子函数。

progress

是否显示构建进度条。

providers

指定提供者配置，用于替换代码中的标识符为 require 模块标识符。

例如：

{
  providers: {
    process: ["process", ""],
    Buffer: ["buffer", "Buffer"],
  },
}

这些配置将在遇到时将标识符 process 和 Buffer 替换为 require 对应模块的代码。

process;
// => require("process")
Buffer;
// => require("buffer").Buffer

publicPath

publicPath 配置。注意：有一个特殊值 "runtime"，这意味着它将切换到运行时模式并使用运行时的 window.publicPath 作为 publicPath。

如果你想在运行时设置 publicPath，请使用 __mako_public_path__。（注：__webpack_public_path__ 也是支持的）

__mako_public_path__ = '/foo/';

px2rem

是否启用 px2rem 转换。

其中 selectorBlackList、selectorWhiteList、selectorDoubleList 均支持传递正则表达式或者字符串，如

"selectorBlackList": [".a", "/.__CustomClass_/"]

被字符 / 包裹的字符串会被当作正则表达式解析。

react

React 相关配置。

例如，

function App() {
  return <div>1</div>;
}

当运行时为 automatic 时，输出如下，

import { jsx as _jsx } from "react/jsx-runtime";
function App() {
  return /*#__PURE__*/ _jsx("div", {
    children: "1",
  });
}

当运行时为 classic 时，输出如下，

function App() {
  return /*#__PURE__*/ React.createElement("div", null, "1");
}

resolve

resolve 配置。

例如，

{
  resolve: {
    alias: [
      ["@", "./src"]
    ],
    extensions: ["js", "jsx", "ts", "tsx"],
  },
}

注意 1：如果你想别名一个目录，请不要添加 /* 后缀，我们目前还不支持这样做。

例如，

{
  resolve: {
    alias: [
-      ["@/src/*", "./src/*"],
+      [ "@/src", "./src"],
    ],
  },
}

注意 2：如果你想要别名指向一个本地路径，请确保添加 ./ 前缀。否则，它将被视为一个依赖模块。

{
  resolve: {
    alias: [
-       ["@/src", "src"],
+       ["@/src", "./src"],
    ],
  },
}

rscClient

与 RSC 客户端相关的配置。

rscServer

与 RSC 服务器相关的配置。

子配置项：

sass

未安装 sass 包。请运行 npm install sass 进行安装。

指定 sass 配置.

例如：

{
  "sourceMap": false
}

stats

是否生成 stats.json 文件。

子配置项：

transformImport

babel-plugin-import 的简化版本，仅支持三个配置项：libraryName，libraryDirectory 和 style，用于满足现有项目中按需加载 antd v4 样式的需求。

例如：

{
  transformImport: {
    libraryName: "antd",
    libraryDirectory: "es",
    style: true,
  },
}

umd

是否输出 umd 格式。

useDefineForClassFields

是否使用 defineProperty 来定义类字段。

watch

与监视相关的配置。

例如，如果你想要忽略根目录下的 foo 目录，你可以这样设置。

{
  watch: {
    ignorePaths: ["foo"],
  },
}

writeToDisk

是否在开发模式下将构建结果写入磁盘。

在 GitHub 上编辑此页