Next.js集成New Relic浏览器代理遇TypeScript类型错误求解

在Next.js的_document.tsx中尝试服务端注入New Relic浏览器代理时，出现TypeScript类型错误，提示browserTimingHeader不属于DocumentInitialProps类型的已知属性。

报错信息：

Type '{ browserTimingHeader: any; html: string; head?: JSX.Element[]; styles?: JSX.Element | ReactElement<any, string | JSXElementConstructor<any>>[] | ReactFragment; }' is not assignable to type 'DocumentInitialProps'. Object literal may only specify known properties, and 'browserTimingHeader' does not exist in type 'DocumentInitialProps'.ts(2322)

解决方案 #

Next.js默认的DocumentInitialProps类型未定义browserTimingHeader字段，以下是两种可行的修复方式：

方法1：扩展Document的Props类型（推荐） #

自定义继承自DocumentInitialProps的类型，添加browserTimingHeader字段，同时为MyDocument类指定泛型参数，实现类型安全：

/* eslint-disable @typescript-eslint/no-var-requires */
// pages/_document.tsx
const newrelic = require("newrelic");
import Document, {
  DocumentContext,
  DocumentInitialProps,
  Html,
  Head,
  Main,
  NextScript,
} from "next/document";
import type { ReactElement } from "react";

// 扩展默认类型，添加自定义字段
interface MyDocumentInitialProps extends DocumentInitialProps {
  browserTimingHeader: string;
}

class MyDocument extends Document<MyDocumentInitialProps> {
  static async getInitialProps(ctx: DocumentContext): Promise<MyDocumentInitialProps> {
    const initialProps = await Document.getInitialProps(ctx);

    const browserTimingHeader = newrelic.getBrowserTimingHeader({
      hasToRemoveScriptWrapper: true,
    });

    return {
      ...initialProps,
      browserTimingHeader,
    };
  }

  render() {
    return (
      <Html>
        <Head>
          {/* 注入New Relic代理脚本 */}
          <script dangerouslySetInnerHTML={{ __html: this.props.browserTimingHeader }} />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

方法2：使用类型断言（临时快速修复） #

如果需要临时绕过类型检查，可通过as断言合并类型：

static async getInitialProps(ctx: DocumentContext): Promise<DocumentInitialProps> {
  const initialProps = await Document.getInitialProps(ctx);

  const browserTimingHeader = newrelic.getBrowserTimingHeader({
    hasToRemoveScriptWrapper: true,
  });

  return {
    ...initialProps,
    browserTimingHeader,
  } as DocumentInitialProps & { browserTimingHeader: string };
}

注意事项 #

• 确保已正确安装newrelic包并配置服务端环境变量
• getBrowserTimingHeader返回的是脚本字符串，需通过dangerouslySetInnerHTML注入到页面头部
• 优先使用方法1的类型扩展方案，以获得完整的TypeScript类型校验，避免潜在问题

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