NodeJS v23原生TS支持下复刻compilerOptions paths配置问询

核心方案：结合TypeScript paths与Node.js Subpath Imports #

Node.js v23原生支持TypeScript，但不会自动处理tsconfig.json中的compilerOptions.paths映射，此时可以通过TypeScript路径别名映射 + Node.js Subpath Imports的组合方案，既满足前端惯用的@/~写法，又符合Node.js的加载规则。

针对你的三点顾虑的具体解决办法 #

1. 适配@/~的惯用写法

在tsconfig.json中配置paths，将@/~开头的别名映射到Node.js要求的#开头子路径，同时在package.json中配置Subpath Imports指向实际文件：

tsconfig.json

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

package.json

{
  "imports": {
    "#utils/*": "./src/utils/*",
    "#config/*": "./src/config/*"
  }
}

开发时你可以继续写import { foo } from '@utils/foo'，TypeScript会识别别名，Node.js加载时会通过package.json的imports字段解析到实际文件路径。

2. 解决前端工具对#的报错问题

大部分前端工具可以通过配置别名规则兼容：

• ESLint：安装tsconfig-paths-eslint-plugin，在.eslintrc中配置：

  {
    "plugins": ["tsconfig-paths"],
    "rules": {
      "tsconfig-paths/no-unused-paths": "warn"
    }
  }
  

• Vite/Webpack：在配置文件中添加对应别名，匹配tsconfig.json的paths：

  // vite.config.js
  export default {
    resolve: {
      alias: {
        '@utils': '/src/utils',
        '@config': '/src/config'
      }
    }
  }
  

通过这些配置，前端工具就能正确识别路径别名，不会出现报错。

3. Subpath Imports的可靠性说明

Node.js的Subpath Imports是从v16开始就进入稳定状态的官方特性，v23完全兼容，属于Node.js模块系统的标准规范，不存在可靠性问题。之所以少见，是因为过去很多项目依赖Babel、ts-node等第三方转译工具实现路径映射，而原生TS支持普及后，这个特性会逐渐成为主流方案。

生产环境适配（无需tsx/ts-node） #

生产环境编译TypeScript时，仅用tsc无法自动转换paths映射，需配合tsc-alias工具：

1. 安装依赖：npm install tsc-alias --save-dev
2. 在package.json的脚本中修改编译命令：

   {
     "scripts": {
       "build": "tsc && tsc-alias"
     }
   }
   

编译后，@/~开头的别名会被转换为相对路径，生产环境的JS文件无需依赖Node.js的Subpath Imports即可正常运行。

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