Next.js元数据ESLint警告处理：正确用法咨询

问题原因 #

React Fast Refresh的ESLint规则react-refresh/only-export-components要求组件文件仅导出React组件，但metadata是Next.js框架定义的特殊导出项，不属于组件范畴，因此触发警告。

处理方案（按推荐优先级排序） #

1. 针对性禁用ESLint规则（官方推荐） #

Next.js官方教程本身就在页面/布局组件文件中直接导出metadata，这是框架标准用法。无需迁移元数据，只需添加ESLint禁用注释：

• 单禁用该行：

// eslint-disable-next-line react-refresh/only-export-components
export const metadata: Metadata = {
  title: 'Dashboard',
  description: 'App Dashboard'
};

• 禁用整个文件的该规则（仅当文件仅包含组件和metadata导出时）：

/* eslint-disable react-refresh/only-export-components */
import type { Metadata } from 'next';

export const metadata: Metadata = { /* ... */ };

export default function Dashboard() {
  return <div>...</div>;
}

2. 全局适配ESLint规则 #

如果不想重复添加注释，可在ESLint配置文件中修改规则，允许Next.js的特殊导出项：

{
  "rules": {
    "react-refresh/only-export-components": [
      "warn",
      {
        "allowExportNames": ["metadata", "generateMetadata", "dynamicParams", "revalidate"]
      }
    ]
  }
}

此配置一劳永逸，既符合Next.js设计，又不影响Fast Refresh功能——框架已对这些特殊导出做了热更新兼容。

3. 不推荐：迁移元数据到单独文件 #

ESLint提示的“用新文件共享常量”不适用于metadata，因为它是页面/布局的专属配置，与组件强关联。迁移会增加不必要的文件拆分，降低代码可读性，仅在元数据需跨多个页面复用且复杂度极高时考虑。

最佳实践 #

• 遵循Next.js官方规范，直接在页面/布局文件中导出metadata
• 通过ESLint规则配置或单行注释解决警告，不要为适配ESLint破坏框架标准用法
• 复杂复用的元数据可封装为generateMetadata函数，仍保留在对应页面/布局文件中

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