Nuxt 3中使用@/或~/路径导入模块报错：Cannot find module

问题原因 #

nuxt.config.ts是Node.js直接加载执行的配置文件，此时Nuxt的路径别名（@/、~/）还未完成初始化与解析，Node本身并不识别这些自定义别名，因此会抛出Cannot find module '~/path'的错误。而相对路径是Node原生支持的模块解析方式，所以可以正常运行。

可行解决方案 #

方案一：使用相对路径（推荐） #

直接保留当前可用的相对路径导入方式，这是最简单且无额外配置的方案：

import headConfig from './config/head/headConfig';

方案二：手动配置Node识别路径别名（按需使用） #

如果必须使用@/别名，需要额外配置让Node解析这个别名：

1. 安装依赖包：

   npm install tsconfig-paths --save-dev
   

2. 确保tsconfig.json中已配置路径别名：

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

3. 修改package.json中的启动命令，通过ts-node配合tsconfig-paths加载配置文件：

   {
     "scripts": {
       "dev": "ts-node -r tsconfig-paths/register node_modules/nuxt/bin/nuxt.mjs dev",
       "build": "ts-node -r tsconfig-paths/register node_modules/nuxt/bin/nuxt.mjs build",
       "generate": "ts-node -r tsconfig-paths/register node_modules/nuxt/bin/nuxt.mjs generate"
     }
   }
   

   注意：该方案会增加配置复杂度，且可能在不同环境下存在兼容性问题，仅在有强烈别名需求时使用。

补充说明 #

Nuxt的@/、~/路径别名仅在业务代码、插件、中间件等经过Nuxt构建流程处理的文件中生效，nuxt.config.ts这类直接由Node执行的配置文件不在此范围内。

内容的提问来源于stack exchange，提问作者Данил Пономаренко