如何在Docusaurus中通过构建环境变量控制自定义组件渲染？

方案一：通过Docusaurus配置注入全局标识（推荐） #

这种方式利用Docusaurus的站点配置传递构建时的标识，步骤如下：

1. 修改docusaurus.config.js
   在配置文件中读取环境变量，添加自定义字段：

module.exports = {
  // 其他原有配置...
  customFields: {
    isNextBranch: process.env.GITHUB_REF === 'refs/heads/next',
  },
};

2. 更新Swizzle后的组件代码
   修改src/theme/DocItem/Content/index.tsx，通过useDocusaurusContext获取站点配置中的标识：

import React from 'react';
import Content from '@theme-original/DocItem/Content';
import type ContentType from '@theme/DocItem/Content';
import type { WrapperProps } from '@docusaurus/types';
import { useDocusaurusContext } from '@docusaurus/theme-common';

type Props = WrapperProps<typeof ContentType>;

function NextBanner(): JSX.Element | null {
  const { siteConfig } = useDocusaurusContext();
  const isNext = siteConfig.customFields.isNextBranch;
  
  if (isNext) {
    return (
      <div className="alert alert--warning margin-bottom--md">
        This is documentation for an unreleased version!
      </div>
    );
  }

  return null;
}

export default function ContentWrapper(props: Props): JSX.Element {
  return (
    <>
      <NextBanner />
      <Content {...props} />
    </>
  );
}

方案二：直接使用构建时注入的环境变量 #

根据Docusaurus版本选择对应方式：

针对Docusaurus v3+（基于Vite）： #

1. 构建时传递带前缀的环境变量
   在流水线的构建命令中传递变量：

VITE_IS_NEXT_BRANCH=$( [ "$GITHUB_REF" = "refs/heads/next" ] && echo "true" || echo "false" ) npm run build

2. 组件中访问变量
   修改组件内的判断逻辑：

function NextBanner(): JSX.Element | null {
  const isNext = import.meta.env.VITE_IS_NEXT_BRANCH;
  
  if (isNext) {
    return (
      <div className="alert alert--warning margin-bottom--md">
        This is documentation for an unreleased version!
      </div>
    );
  }

  return null;
}

针对Docusaurus v2（基于Webpack）： #

1. 构建时传递带前缀的环境变量
   在流水线的构建命令中传递变量：

REACT_APP_IS_NEXT_BRANCH=$( [ "$GITHUB_REF" = "refs/heads/next" ] && echo "true" || echo "false" ) npm run build

2. 组件中访问变量
   修改组件内的判断逻辑：

function NextBanner(): JSX.Element | null {
  const isNext = process.env.REACT_APP_IS_NEXT_BRANCH === 'true';
  
  if (isNext) {
    return (
      <div className="alert alert--warning margin-bottom--md">
        This is documentation for an unreleased version!
      </div>
    );
  }

  return null;
}

原代码失效原因 #

Docusaurus构建静态站点时，React组件最终会被编译为浏览器可执行代码，而浏览器环境不存在process对象，因此直接在组件中访问process.env会报错。必须通过构建工具将环境变量注入代码，或通过Docusaurus的配置上下文传递标识。

内容的提问来源于stack exchange，提问作者void.pointer