为何Node/Nest无法识别src目录下的本地node-os-utils模块？

问题场景 #

我有一个NestJS项目，为调试正在使用的node-os-utils模块，将其从node_modules目录复制到src目录下，把原本的导入语句：

import * as osutils from 'node-os-utils'

改为：

import * as osutils from './node-os-utils'

但运行时出现模块找不到的错误，报错信息如下：

my_api | Error: Cannot find module './node-os-utils'
my_api | Require stack:
my_api | - /api/dist/src/app.service.js
my_api | - /api/dist/src/app.controller.js
my_api | - /api/dist/src/app.module.js
my_api | - /api/dist/src/main.js
my_api |     at Function.Module._resolveFilename (node:internal/modules/cjs/loader:1075:15)
my_api |     at Function.Module._load (node:internal/modules/cjs/loader:920:27)
my_api |     at Module.require (node:internal/modules/cjs/loader:1141:19)
my_api |     at require (node:internal/modules/cjs/helpers:110:18)
my_api |     at Object.<anonymous> (/api/src/app.service.ts:6:1)
my_api |     at Module._compile (node:internal/modules/cjs/loader:1254:14)
my_api |     at Object.Module._extensions..js (node:internal/modules/cjs/loader:1308:10)
my_api |     at Module.load (node:internal/modules/cjs/loader:1117:32)
my_api |     at Function.Module._load (node:internal/modules/cjs/loader:958:12)
my_api |     at Module.require (node:internal/modules/cjs/loader:1141:19)

明明目录结构一致，为何无法通过这种方式导入模块？

问题原因 #

1. 编译产物缺失：NestJS基于TypeScript编译，默认仅处理src下的TS文件，复制到src的node-os-utils是JS模块，编译时不会自动复制到dist/src目录，导致运行时找不到对应文件。
2. 模块入口解析失败：node-os-utils的package.json定义了入口文件（如lib/index.js），但直接导入目录时，Node.js需要在dist对应的目录下找到入口文件或package.json，而未被复制的模块目录无法满足这个条件。
3. TS配置未覆盖模块目录：如果tsconfig.json的include规则未包含src/node-os-utils，TypeScript编译时会忽略该目录，进一步导致产物缺失。

解决方法 #

方法一：临时手动同步目录 #

每次编译后，手动将src/node-os-utils复制到dist/src目录，确保运行时路径匹配，适合临时快速调试。

方法二：修改TS配置自动同步 #

在tsconfig.json中调整配置，让编译过程包含并处理该模块：

{
  "compilerOptions": {
    "outDir": "./dist",
    "allowJs": true, // 允许编译JS文件
    // 其他原有配置...
  },
  "include": [
    "src/**/*",
    "src/node-os-utils/**/*" // 包含模块所有文件
  ]
}

方法三：用路径别名无需修改导入语句 #

在tsconfig.json配置路径别名，直接将node-os-utils指向本地模块，保留原有导入语句：

{
  "compilerOptions": {
    "paths": {
      "node-os-utils": ["./src/node-os-utils"]
    },
    // 其他原有配置...
  }
}

同时确保nest-cli.json关联TS配置：

{
  "compilerOptions": {
    "tsConfigPath": "./tsconfig.json"
  }
}

方法四：npm link关联本地模块 #

将node-os-utils复制到项目外的独立目录，在该目录执行npm link，再在NestJS项目中执行npm link node-os-utils，项目会自动使用本地模块版本，无需修改导入语句，调试更高效。

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