nextjs build_error ai_generated true

错误：发现重复的 <head> 元素。每个文档只允许一个 <head> 元素。

Error: Duplicate <head> element found. Only one <head> element is allowed per document.

ID: nextjs/next-head-element-duplicate

其他格式: JSON · Markdown 中文 · English
95%修复率
88%置信度
1证据数
2023-11-20首次发现

版本兼容性

版本状态引入弃用备注
[email protected] active — — —
[email protected] active — — —
[email protected] active — — —

根因分析

在 Next.js app 目录中，多个布局或页面导出了 <head> 元素，导致 HTML 输出中出现重复的 head 标签。

English

In Next.js app directory, multiple layouts or pages export <head> elements, causing duplicate head tags in the HTML output.

generic

官方文档

https://nextjs.org/docs/app/building-your-application/optimizing/metadata

解决方案

  1. 从布局和页面中移除所有手动 <head> 标签。在根布局中使用 generateMetadata 设置元数据：

export const metadata = {
  title: '我的应用',
  description: '描述',
};

然后在子页面中导出 generateMetadata 来覆盖特定值。
  2. 如果使用自定义根布局，确保根 layout.tsx 文件中只有一个 <head> 标签，并从子组件中移除。
  3. 对于使用 pages 目录的旧页面，保留 next/head，但避免与 app 目录布局混合。

无效尝试

常见但无效的做法:

  1. 95% 失败

    This creates multiple head elements, which is exactly the error. Metadata should be centralized.

  2. 85% 失败

    next/head is deprecated in the app directory; it causes hydration errors and duplicate head issues.

  3. 100% 失败

    The build will fail; this is a blocking error that prevents successful compilation.