NextJS应用无法识别_document.tsx文件，求原因及解决方法

核心原因 #

你当前使用的是Next.js App Router（项目目录为src/app，无根pages文件夹），而_document.tsx是Pages Router的专属自定义文件，App Router完全不识别这个文件，所以无论你把它放在哪个路径都不会生效。

正确解决方案（App Router替代方案） #

在App Router中，自定义全局HTML结构的功能由**根布局文件src/app/layout.tsx**承担，你需要将原_document.tsx中的逻辑迁移到这个文件中：

步骤1：确认根布局文件位置 #

确保你的项目存在src/app/layout.tsx（这是App Router的必填文件，若不存在则新建）。

步骤2：修改根布局文件 #

将Heap分析脚本和全局HTML结构迁移到layout.tsx，示例代码如下：

import type { Metadata } from 'next';
import Script from 'next/script';

// 可选：配置全局元数据
export const metadata: Metadata = {
  title: '你的应用标题',
  description: '你的应用描述',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // 注意：此console.log会输出在服务器终端，而非浏览器控制台（根布局默认是服务器组件）
  console.log("this is root layout talking");
  
  return (
    <html lang="zh-CN">
      <head>
        {/* 使用beforeInteractive策略确保脚本在页面交互前加载，和原_document.tsx效果一致 */}
        <Script id="heap-analytics" strategy="beforeInteractive">
          {`window.heap=window.heap||[],heap.load=function(e,t){window.heap.appid=e,window.heap.config=t=t||{};var r=document.createElement("script");r.type="text/javascript",r.async=!0,r.src="https://cdn.heapanalytics.com/js/heap-"+e+".js";var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(r,a);for(var n=function(e){return function(){heap.push([e].concat(Array.prototype.slice.call(arguments,0)))}},p=["addEventProperties","addUserProperties","clearEventProperties","identify","resetIdentity","removeEventProperty","setEventProperties","track","unsetEventProperty"],o=0;o<p.length;o++)heap[p[o]]=n(p[o])};
  heap.load("123456789");`}
        </Script>
      </head>
      <body>
        {children}
      </body>
    </html>
  );
}

关键注意事项 #

• App Router完全废弃了Pages Router的特殊文件（包括_document.tsx、_app.tsx），所有全局结构和逻辑都通过根布局layout.tsx处理
• 根布局默认是服务器组件，所以console.log会输出在服务器终端，而非浏览器控制台，这也是你之前看不到_document.tsx中日志的原因（原_document.tsx的render也是在服务器端执行）
• 若需要添加更多全局HTML元素（如自定义meta标签、lang属性），直接在根布局的<html>或<head>标签内修改即可

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