VS Code中tsconfig paths无法生效的问题求助

问题详情 #

开发Discord Bot过程中，通过tsconfig.json配置了路径别名，但运行编译后的代码时，Node.js无法识别这些别名，抛出MODULE_NOT_FOUND错误。尽管Bot能启动，但使用别名导入的功能完全无法工作。已尝试调整includes、baseUrl、rootDir等配置项，问题仍未解决。

调试控制台错误信息 #

Debugger attached.
Error when loading '/home/tai/dev/FutabaBot/dist/commands/moderation/mute.js': Error: Cannot find module '#util/functions'
Require stack:
- /home/tai/dev/FutabaBot/dist/commands/moderation/mute.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/lib/strategies/LoaderStrategy.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/index.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/lib/utils/application-commands/ApplicationCommandRegistries.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/index.js
- /home/tai/dev/FutabaBot/dist/lib/FutabaClient.js
- /home/tai/dev/FutabaBot/dist/FutabaBot.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/home/tai/dev/FutabaBot/dist/commands/moderation/mute.js:10:21)
    at Module._compile (node:internal/modules/cjs/loader:1103:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1157:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Module.require (node:internal/modules/cjs/loader:1005:19) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/home/tai/dev/FutabaBot/dist/commands/moderation/mute.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/lib/strategies/LoaderStrategy.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/index.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/lib/utils/application-commands/ApplicationCommandRegistries.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/index.js',
    '/home/tai/dev/FutabaBot/dist/lib/FutabaClient.js',
    '/home/tai/dev/FutabaBot/dist/FutabaBot.js'
  ]
}
Error when loading '/home/tai/dev/FutabaBot/dist/commands/moderation/kick.js': Error: Cannot find module '#util/functions'
Require stack:
- /home/tai/dev/FutabaBot/dist/commands/moderation/kick.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/lib/strategies/LoaderStrategy.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/index.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/lib/utils/application-commands/ApplicationCommandRegistries.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/index.js
- /home/tai/dev/FutabaBot/dist/lib/FutabaClient.js
- /home/tai/dev/FutabaBot/dist/FutabaBot.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/home/tai/dev/FutabaBot/dist/commands/moderation/kick.js:17:21)
    at Module._compile (node:internal/modules/cjs/loader:1103:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1157:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Module.require (node:internal/modules/cjs/loader:1005:19) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/home/tai/dev/FutabaBot/dist/commands/moderation/kick.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/lib/strategies/LoaderStrategy.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/index.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/lib/utils/application-commands/ApplicationCommandRegistries.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/index.js',
    '/home/tai/dev/FutabaBot/dist/lib/FutabaClient.js',
    '/home/tai/dev/FutabaBot/dist/FutabaBot.js'
  ]
}
Error when loading '/home/tai/dev/FutabaBot/dist/commands/moderation/ban.js': Error: Cannot find module '#util/functions'
Require stack:
- /home/tai/dev/FutabaBot/dist/commands/moderation/ban.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/lib/strategies/LoaderStrategy.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/index.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/lib/utils/application-commands/ApplicationCommandRegistries.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/index.js
- /home/tai/dev/FutabaBot/dist/lib/FutabaClient.js
- /home/tai/dev/FutabaBot/dist/FutabaBot.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/home/tai/dev/FutabaBot/dist/commands/moderation/ban.js:17:21)
    at Module._compile (node:internal/modules/cjs/loader:1103:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1157:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Module.require (node:internal/modules/cjs/loader:1005:19) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/home/tai/dev/FutabaBot/dist/commands/moderation/ban.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/lib/strategies/LoaderStrategy.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/index.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/lib/utils/application-commands/ApplicationCommandRegistries.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/index.js',
    '/home/tai/dev/FutabaBot/dist/lib/FutabaClient.js',
    '/home/tai/dev/FutabaBot/dist/FutabaBot.js'
  ]
}
Error when loading '/home/tai/dev/FutabaBot/dist/listeners/ready.js': Error: Cannot find module './utils'
Require stack:
- /home/tai/dev/FutabaBot/dist/lib/util/Timers.js
- /home/tai/dev/FutabaBot/dist/lib/ModerationService.js
- /home/tai/dev/FutabaBot/dist/listeners/ready.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/lib/strategies/LoaderStrategy.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/index.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/lib/utils/application-commands/ApplicationCommandRegistries.js
- /home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/index.js
- /home/tai/dev/FutabaBot/dist/lib/FutabaClient.js
- /home/tai/dev/FutabaBot/dist/FutabaBot.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/home/tai/dev/FutabaBot/dist/lib/util/Timers.js:6:17)
    at Module._compile (node:internal/modules/cjs/loader:1103:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1157:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Module.require (node:internal/modules/cjs/loader:1005:19) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/home/tai/dev/FutabaBot/dist/lib/util/Timers.js',
    '/home/tai/dev/FutabaBot/dist/lib/ModerationService.js',
    '/home/tai/dev/FutabaBot/dist/listeners/ready.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/lib/strategies/LoaderStrategy.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/pieces/dist/index.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/lib/utils/application-commands/ApplicationCommandRegistries.js',
    '/home/tai/dev/FutabaBot/node_modules/@sapphire/framework/dist/index.js',
    '/home/tai/dev/FutabaBot/dist/lib/FutabaClient.js',
    '/home/tai/dev/FutabaBot/dist/FutabaBot.js'
  ]
}

当前tsconfig.json配置 #

{
    "extends": "@sapphire/ts-config",
    "compilerOptions": {
        "target": "ES2020",
        "rootDir": ".",
        "outDir": "./dist/",
        "strict": true,
        "skipLibCheck": true,
        "types": ["node"],
        "inlineSources": true,
        "allowJs": true,
        "baseUrl": "./src",
        "paths": {
            "#util/*": ["lib/util/*"],
            "#lib/*": ["lib/*"]
        }
    },
    "include": ["."]
}

问题原因 #

1. Node.js不识别TypeScript路径别名：TypeScript的paths配置只是编译阶段的语法糖，编译后的JS文件中会保留#util/functions这类别名路径，但Node.js原生模块加载器无法解析这类自定义别名，导致找不到模块。
2. rootDir配置错误：rootDir设为.会导致TypeScript将项目根目录下所有文件都作为源码编译，输出到dist后文件结构混乱，破坏了路径映射的对应关系。
3. 相对路径解析异常：最后一个错误中./utils找不到，是因为编译后的文件结构和源码结构不一致，相对路径指向了错误的位置。

解决方法 #

1. 让Node.js识别路径别名 #

安装tsconfig-paths包，在运行时加载路径映射规则：

npm install tsconfig-paths --save-dev

修改启动脚本，添加路径注册：

node -r tsconfig-paths/register dist/FutabaBot.js

或者使用module-alias包，在入口文件FutabaBot.js顶部添加：

const moduleAlias = require('module-alias');
moduleAlias.addAliases({
  '#util': __dirname + '/lib/util',
  '#lib': __dirname + '/lib'
});

2. 修正tsconfig核心配置 #

调整rootDir和include，确保编译范围和输出结构正确：

{
    "extends": "@sapphire/ts-config",
    "compilerOptions": {
        "target": "ES2020",
        "rootDir": "./src", // 仅将src目录作为源码根目录
        "outDir": "./dist/",
        "strict": true,
        "skipLibCheck": true,
        "types": ["node"],
        "inlineSources": true,
        "allowJs": true,
        "baseUrl": "./src",
        "paths": {
            "#util/*": ["lib/util/*"],
            "#lib/*": ["lib/*"]
        }
    },
    "include": ["./src/**/*"] // 仅编译src下的所有文件
}

3. 修复相对路径错误 #

检查src/lib/util/Timers.ts中的./utils导入，确保目标文件存在于同一目录下，且编译后dist/lib/util/目录下包含对应的utils.js文件。如果是导入目录，确保目录下有index.js或index.ts作为入口。

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