TypeScript中next/google/font模块找不到及导入语法困惑

问题背景 #

• Next.js官方文档给出的字体导入语法import { <font-name> } from 'next/google/font';可编译，但运行时抛出“module not found”错误
• 部分社区讨论中的import { <font-name> } from '@next/google/font';语法在编译阶段直接报错，用户无法明确正确的导入路径，报错信息也未给出有效指引
• 问题发生在Nrwl NX monorepo的Next.js项目中，尝试添加@types/next依赖、自定义模块声明、@nrwl/next/google/font导入等方法均未解决

解决步骤 #

1. 对齐Next.js版本
   字体优化的next/font/*系列API是Next.js 13.0.0及以上版本的特性，确认子项目的Next.js版本符合要求。NX monorepo中要保证子项目依赖与根目录依赖版本一致，避免版本不兼容导致的模块解析问题。

2. 修正导入路径
   官方文档存在旧路径的笔误，最新的正确导入路径应为：

   import { <font-name> } from 'next/font/google';
   

   替换<font-name>为实际字体名（如Roboto、Inter等）。

3. 排查NX模块解析配置
   检查根目录和子项目的tsconfig.json，确保没有自定义的路径映射干扰next模块的解析。NX的compilerOptions.paths中若存在next相关配置，可能导致内置模块无法被正确识别，需移除或调整。

4. 清理依赖缓存
   执行以下命令清理缓存并重新安装依赖，解决潜在的依赖损坏问题：

   # 针对Yarn
   yarn cache clean && yarn install
   # 针对NX项目重置缓存
   nx reset
   

5. 移除冗余类型依赖
   Next.js 13+自带完整的类型定义，无需手动安装@types/next。若之前添加过该依赖，建议从package.json中移除，避免类型冲突。

验证示例 #

导入并使用字体的示例代码：

import { Roboto } from 'next/font/google';

// 配置字体子集与权重
const roboto = Roboto({
  subsets: ['latin'],
  weight: ['400', '700']
});

export default function HomePage() {
  return (
    <div className={roboto.className}>
      <h1>测试字体导入</h1>
    </div>
  );
}

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