使用process.env设置Docusaurus的url致构建失败，如何动态配置多子域名？

问题原因 #

Docusaurus对顶层的url字段有必填校验，构建时会优先检查该字段是否存在有效值。如果直接使用process.env.DOCUSAURUS_URL，当环境变量未正确注入或加载时机滞后时，该值会是undefined，从而触发"url is required"的错误。而customFields属于自定义字段，Docusaurus不会对其做必填校验，所以环境变量能正常生效。

解决方案 #

1. 确保环境变量正确注入并添加默认值

在docusaurus.config.js中给url字段设置默认值，避免环境变量未传入时触发校验错误：

const config = {
  // ...其他配置项
  url: process.env.DOCUSAURUS_URL || 'https://docs.mydomain.com', // 设置默认域名作为 fallback
  // ...其他配置项
};

module.exports = config;

然后在构建时通过命令行指定环境变量：

# 构建test子域名版本
DOCUSAURUS_URL=https://test.mydomain.com npm run build

# 构建docs子域名版本（可省略命令行参数，因为有默认值）
npm run build

如果需要跨平台兼容（Windows/Linux/macOS），可以使用cross-env包消除系统差异：
首先安装依赖：

npm install cross-env --save-dev

然后在package.json的scripts中添加封装后的构建命令：

{
  "scripts": {
    "build:test": "cross-env DOCUSAURUS_URL=https://test.mydomain.com npm run build",
    "build:docs": "npm run build"
  }
}

之后直接运行对应命令即可：

# 构建test子域名站点
npm run build:test

# 构建docs子域名站点
npm run build:docs

2. 动态导出配置函数（可选）

如果需要更复杂的配置逻辑，可以将配置改为函数导出形式，确保环境变量加载完成后再生成最终配置：

module.exports = function getConfig() {
  const siteUrl = process.env.DOCUSAURUS_URL || 'https://docs.mydomain.com';
  
  return {
    // ...其他配置项
    url: siteUrl,
    // 可根据url动态调整其他关联配置，比如baseUrl等
    baseUrl: '/',
    // ...其他配置项
  };
};

关键注意点 #

• 环境变量必须在构建命令执行前注入，Docusaurus作为静态站点生成器，所有站点配置都会在构建阶段确定，运行时无法修改。
• 始终给url字段设置默认值，防止因环境变量未传入或注入失败导致构建中断。

内容的提问来源于stack exchange，提问作者Nicos