Next.js 13 App目录结构下如何添加自定义Document？

核心解决思路 #

Next.js 13的App Router不再使用pages/_document.js，转而用app/layout.js负责全局布局配置，但如果你的设计系统强制要求基于pages目录的自定义Document，最直接的兼容方式是采用混合目录结构——同时保留pages和app目录，既满足设计系统的配置要求，又能正常使用App Router的新特性。

具体操作步骤 #

• 保留项目根目录的pages文件夹，在其中创建_document.js（或.tsx），严格按照设计系统要求完成配置：

  import Document, { Html, Head, Main, NextScript } from 'next/document'
  
  class MyDocument extends Document {
    static async getInitialProps(ctx) {
      const initialProps = await Document.getInitialProps(ctx)
      // 这里添加设计系统要求的自定义逻辑，比如注入全局样式、自定义属性等
      return initialProps
    }
  
    render() {
      return (
        <Html>
          <Head>
            {/* 设计系统要求的全局资源，比如字体、样式文件等 */}
          </Head>
          <body>
            <Main />
            <NextScript />
          </body>
        </Html>
      )
    }
  }
  
  export default MyDocument
  

• 正常在app目录下开发页面和布局，Next.js会自动识别混合目录结构，优先遵循App Router的路由规则，但_document.js的全局配置依然会生效——毕竟Document是全局层面的配置，和路由模式无关。
• 注意：混合模式下，不要在app和pages目录中创建路由路径重复的文件，避免路由冲突。

纯App Router替代方案 #

如果不想保留pages目录，可以通过app/layout.js实现类似自定义Document的功能：

• 在app/layout.js中直接修改根html、body标签的属性，注入设计系统需要的全局资源：

  export default function RootLayout({ children }) {
    return (
      <html lang="zh-CN" className="design-system-root">
        <head>
          {/* 注入设计系统需要的全局样式、meta标签等 */}
        </head>
        <body className="design-system-body">
          {children}
        </body>
      </html>
    )
  }
  

• 对于设计系统中依赖Document.getInitialProps的逻辑，可以迁移到app/layout.js的generateMetadata方法或服务器组件的初始化逻辑中，也可以直接联系设计系统维护者，获取针对App Router的适配方案。

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