#配置使用

Modern.js 中有两种配置，一个是编译时配置，一个是服务端运行时配置。

编译时配置可以在两个位置进行配置：

• 根路径下的 modern.config.(ts|js|mjs) 文件
• package.json 文件

服务端运行时配置可以在根路径下的 modern.server-runtime.config.(ts|js|mjs) 中自定义配置选项。

#在配置文件中配置

Modern.js 的配置文件定义在项目的根目录下，支持 .js, .ts 和 .mjs 格式：

• modern.config.js
• modern.config.ts
• modern.config.mjs

#modern.config.js

modern.config.js 中可以使用 JavaScript 语法，因此比 package.json 更加灵活。

比如，你可以在 modern.config.js 中定义函数类型的配置选项：

export default {
  source: {
    alias: opts => {
      opts['@common'] = './src/common';
    },
  },
};

你也可以通过 process.env.NODE_ENV 进行动态设置：

export default {
  server: {
    ssr: process.env.NODE_ENV === 'development',
  },
};

#modern.config.ts（推荐）

我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。

从 @modern-js/app-tools 中导入 defineConfig 工具函数, 它会帮助你进行配置的类型推导和类型补全：

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  source: {
    alias: {
      '@common': './src/common',
    },
  },
});

#导出配置函数

Modern.js 支持在配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Modern.js。

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig(({ env, command }) => ({
  source: {
    alias: {
      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
    },
  },
}));

该函数接受以下入参：

• env：对应 process.env.NODE_ENV 的值。
  • 当运行 modern dev 或 modern start 时，env 的值为 development。
  • 当运行 modern build 或 modern serve 时，env 的值为 production。
  • 当运行 modern test 时，env 的值为 test。
• command: 对应当前运行的命令，如 dev、start、build、serve。

#导出异步函数

Modern.js 也支持在配置文件中导出一个异步函数，你可以在函数中进行一些异步操作：

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig(async ({ env, command }) => {
  const result = await someAsyncFunction();

  return {
    html: {
      title: result,
    },
  };
});

#指定配置文件

Modern.js 命令行支持通过 --config 选项来指定配置文件的名称。

例如，你需要在执行 build 命令时使用 modern.prod.config.ts 文件，可以在 package.json 中添加如下配置：

{
  "scripts": {
    "dev": "modern modern",
    "build": "modern build --config modern.prod.config.ts"
  }
}

你也可以将 --config 选项缩写为 -c：

$ modern build -c modern.prod.config.js

#在 package.json 中配置（不推荐）

除了配置文件外，也可以在 package.json 中的 modernConfig 字段下设置配置选项，如：

{
  "modernConfig": {
    "source": {
      "alias": {
        "@common": "./src/common"
      }
    }
  }
}

由于 JSON 文件格式的限制，package.json 中只能定义数字、字符串、布尔值、数组等简单类型的值，当我们需要设置函数类型的值时，建议在 Modern.js 配置文件中进行设置。

#注意事项

• 不建议同时使用 package.json 和 modern.config.js 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示。
• @modern-js/runtime 导出了同名的 defineConfig API，请注意区分。

#本地调试配置

为了便于本地调试配置，Modern.js 支持在项目根目录下创建 modern.config.local.(ts|js|mjs) 文件，用于覆盖 modern.config.(ts|js|mjs) 中的配置选项。

#示例

比如，项目的 modern.config.ts 中配置了端口号为 3000:

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  server: {
    port: 3000,
  },
});

如果你在本地调试时需要将端口号修改为 3001，但是又不希望修改当前项目的 modern.config.ts 文件，那么可以创建一个 modern.config.local.ts 文件，并添加以下配置：

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  server: {
    port: 3001,
  },
});

modern.config.local.ts 文件中的配置会与 modern.config.ts 中的配置进行深层合并，并覆盖 modern.config.ts 中的配置选项，因此 server.port 会被覆盖为 3001。

#注意事项

在使用 modern.config.local.ts 时，请注意以下事项：

• modern.config.local.ts 文件仅会在执行 modern dev 或 modern start 命令时被加载，当执行 modern build 时不会被加载。
• modern.config.local.ts 文件的优先级不仅高于 modern.config.ts，也高于 package.json 中的 modernConfig 字段。
• 由于 modern.config.local.ts 仅在本地调试时使用，因此不建议将其提交到代码仓库中，请确保项目的 .gitignore 文件中包含 modern.config.local.ts 等文件。

modern.config.local.ts
modern.config.local.js
modern.config.local.mjs