Next.js public文件夹存放woff2文件未引用仍触发编译报错问题

问题触发原因 #

Next.js默认不会将public目录下的文件作为源码模块扫描编译，该目录下的资源默认直接作为静态托管资源使用，触发这个报错本质是你的项目配置修改了默认的扫描规则，导致webpack把public下的字体文件当成了需要编译的模块处理，常见的配置改动场景如下：

• tsconfig.json/jsconfig.json的include字段手动添加了public目录，导致类型检查/打包工具扫描到该目录下的二进制文件
• 你自定义了next.config.js里的webpack规则，配置的模块匹配规则覆盖了默认的public排除逻辑
• 引入的第三方Next.js插件（比如字体处理、静态资源扫描类插件）默认开启了全目录扫描，没有排除public目录
• 错误将public目录放在了src源码目录下，导致被识别为源码的一部分触发编译

禁止Next.js扫描public目录的解决方案 #

方案1：调整webpack配置强制排除public目录 #

在根目录的next.config.js中添加如下配置，让webpack跳过对public目录下所有文件的解析：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    // 为所有现有规则添加public目录排除逻辑
    config.module.rules.forEach(rule => {
      if (rule.test && !rule.exclude) {
        rule.exclude = /\/public\//
      } else if (rule.exclude && Array.isArray(rule.exclude)) {
        rule.exclude.push(/\/public\//)
      }
    })
    // 额外配置noParse直接跳过字体类二进制文件解析
    config.module.noParse = /\.(woff2|woff|ttf|eot)$/
    return config
  }
}

module.exports = nextConfig

方案2：修正tsconfig/jsconfig的扫描范围 #

检查根目录下的tsconfig.json或jsconfig.json，确认include数组中没有包含public相关的路径，同时在exclude中添加public目录，参考配置如下：

{
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules", "public"]
}

方案3：排查第三方插件配置 #

如果你的项目引入了next-fonts、next-images这类静态资源处理插件，在插件配置中添加exclude规则过滤public目录，以next-fonts为例：

const withFonts = require('next-fonts')({
  exclude: /\/public\//
})
const nextConfig = withFonts({/* 其余项目配置 */})

方案4：修正public目录位置 #

确认你的public目录存放在项目根目录，和src、next.config.js平级，不要放在src目录内部。

内容的提问来源于stack exchange，提问作者Flex Elektro Deimling