Next.js路径别名代码配置方法及配置失效问题排查

如何通过代码方式动态配置Next.js路径别名 #

jsconfig.json是纯JSON格式文件，确实不支持编写动态逻辑，要实现代码化的别名配置，直接在项目根目录的next.config.js中修改webpack解析配置即可，该文件为Node.js脚本，支持任意逻辑编写：

// next.config.js
const path = require('path')
const fs = require('fs')

// 示例：动态扫描components目录下的所有文件夹，自动生成指向对应目录Exports.js的别名
const componentsPath = path.resolve(__dirname, 'components')
const dynamicAliases = fs.readdirSync(componentsPath).reduce((aliasMap, dirName) => {
  const dirFullPath = path.resolve(componentsPath, dirName)
  if (fs.statSync(dirFullPath).isDirectory()) {
    aliasMap[dirName] = path.resolve(dirFullPath, 'Exports.js')
  }
  return aliasMap
}, {
  // 固定别名配置
  '@': componentsPath
})

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    // 合并自定义别名到webpack解析规则
    config.resolve.alias = {
      ...config.resolve.alias,
      ...dynamicAliases
    }
    return config
  }
}

module.exports = nextConfig

配置完成后重启Next.js开发服务即可生效，可以根据业务需求在该文件中编写任意Node.js逻辑生成别名规则，没有JSON格式的限制。

jsconfig.json中paths配置不生效的原因 #

配置失效的核心原因共3个：

• 缺少通配符匹配规则
  paths配置的匹配规则支持*通配符，配置的"@": ["components"]只能精确匹配import xxx from '@'这一种导入语句，无法匹配@/Button这类带子路径的导入。如果要匹配所有@/开头的路径，需要按如下格式配置：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["components/*"]
    }
  }
}

• 混淆了jsconfig.json的作用
  jsconfig.json/tsconfig.json中的paths配置仅用于编辑器（如VS Code）的路径跳转、类型提示，不会被Next.js构建流程读取。只在jsconfig中配置规则，构建阶段webpack根本识别不到对应别名，自然会报模块找不到的错误，构建端的别名必须通过上面提到的next.config.js中webpack配置实现，jsconfig的paths只需要和webpack别名保持一致，用来消除编辑器报红即可。
• 路径映射和实际文件位置不匹配
  配置@映射到components目录后，尝试导入@/Button，但实际Button.js存放在components/Shared/目录下，就算配置正确，这个导入路径也找不到对应文件，正确路径应该是@/Shared/Button。

配置Index别名指向components/Index/Exports不生效的问题，本质也是上述第二个原因：只在jsconfig中配置了规则，没有在webpack alias中添加对应映射，构建阶段无法识别该别名，在next.config.js的alias中补上Index: path.resolve(__dirname, 'components/Index/Exports.js')即可正常导入。

注意：配置修改后必须重启Next.js开发服务，配置才会生效，热更新不会读取next.config.js和jsconfig.json的修改。

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