Next.js项目构建时import type声明失败，无法导入Metadata类型

可能的原因及修复步骤 #

1. 检查并升级TypeScript版本 #

Next.js 13+的Metadata类型依赖TypeScript 5.0及以上版本，低版本TS可能不兼容import type语法或相关类型定义：

• 执行npm list typescript查看当前版本
• 版本过低则升级：npm install typescript@latest --save-dev

2. 修正tsconfig.json配置 #

排除node_modules是正常操作，但需确保配置符合Next.js官方规范，避免类型解析失败：

• 确认compilerOptions和include配置正确，参考示例：

  {
    "compilerOptions": {
      "target": "ESNext",
      "module": "ESNext",
      "moduleResolution": "bundler",
      "allowJs": true,
      "strict": true,
      "esModuleInterop": true,
      "skipLibCheck": true,
      "forceConsistentCasingInFileNames": true,
      "isolatedModules": true,
      "jsx": "preserve",
      "incremental": true,
      "plugins": [{"name": "next"}]
    },
    "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
    "exclude": ["node_modules"]
  }
  

• 重点：include必须包含.next/types/**/*.ts，这是Next.js自动生成的类型文件，缺失会导致类型无法识别。

3. 验证文件语法与扩展名 #

• 确认layout.tsx的import type { Metadata } from 'next'行无拼写、符号或空格错误
• 确保文件后缀为.tsx（已满足）

4. 清除缓存并重启服务 #

• 删除.next目录及node_modules/.cache（若存在）
• 重启开发服务：npm run dev
• 重新执行构建：npm run build

关于排除node_modules的说明 #

排除node_modules是正确配置，TypeScript默认会忽略该目录下的文件，Next.js的类型定义通过官方插件和next-env.d.ts处理，只要include配置正确，不会影响next模块的类型导入。

内容的提问来源于stack exchange，提问作者matt-harro