如何在Next.js不同部署阶段配置Sentry的environment参数？

核心思路：实现运行时动态环境标识 #

由于构建时的.env无法满足多部署阶段的动态区分需求，我们需要将环境标识的获取延迟到运行时，同时保留.env的配置习惯。

方法1：通过SSR注入运行时环境变量 #

Next.js虽废弃了publicRuntimeConfig，但可通过服务端渲染（SSR）传递动态环境变量，覆盖Sentry的初始化配置：

• 在pages/_app.js中，通过服务端逻辑获取当前部署的环境变量，再传递给客户端更新Sentry的环境标识：

  import { useEffect } from 'react';
  import * as Sentry from '@sentry/nextjs';
  
  function MyApp({ Component, pageProps, runtimeEnv }) {
    useEffect(() => {
      // 更新Sentry的环境标识
      Sentry.configureScope(scope => {
        scope.setEnvironment(runtimeEnv);
      });
    }, [runtimeEnv]);
  
    return <Component {...pageProps} />;
  }
  
  // 服务端获取运行时环境变量（比如部署服务器上的环境变量）
  export async function getServerSideProps() {
    const runtimeEnv = process.env.RUNTIME_ENVIRONMENT_NAME || 'production';
    return { props: { runtimeEnv } };
  }
  
  export default MyApp;
  

  每次请求时，服务端会将当前部署的环境信息传递给客户端，确保Sentry捕获的错误关联正确的部署阶段。

方法2：将部署阶段嵌入Sentry Release版本号 #

除了直接设置environment，还可以把部署阶段信息组合到Sentry的release字段中，实现多环境区分：

• 构建时结合CI的部署标识生成带阶段信息的版本号：

  # 示例：在CI构建时设置RELEASE变量，比如 staging/production
  RELEASE="v1.2.3-${DEPLOY_STAGE}" npm run build
  

• 在sentry.client.config.js和sentry.server.config.js中使用该版本号：

  import * as Sentry from '@sentry/nextjs';
  
  Sentry.init({
    dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
    release: process.env.RELEASE,
    environment: process.env.BASE_ENV || 'production'
  });
  

  在Sentry后台，你可以通过release字段的后缀快速区分不同部署阶段的错误数据。

方法3：动态加载运行时配置文件 #

如果部署环境支持挂载动态配置文件，可以在public目录下放置一个config.json（部署时根据阶段替换）：

{
  "environment": "staging"
}

然后在客户端初始化Sentry前先请求该配置文件：

// sentry.client.config.js
import * as Sentry from '@sentry/nextjs';

async function initSentry() {
  const configRes = await fetch('/config.json');
  const config = await configRes.json();
  
  Sentry.init({
    dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
    environment: config.environment
  });
}

initSentry();

注意：这种方式会轻微延迟Sentry初始化，需权衡错误捕获的覆盖范围。

关键注意事项 #

• 前端可访问的环境变量需添加NEXT_PUBLIC_前缀，避免敏感信息泄露。
• 若使用Vercel等平台的多环境部署，可直接利用平台的环境变量分组功能，部署时动态注入RUNTIME_ENVIRONMENT_NAME，无需修改构建流程。

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