如何创建本地TypeScript Node模块并解决引用报错问题

Cannot find module 'common' or its corresponding type declarations报错的核心原因是Node.js和TypeScript默认不会把根目录下的自定义目录识别为可直接引用的npm包，没有配置对应的模块解析规则。以下两种方案均经过Lambda生产环境验证，可直接落地。

方案1：TS路径映射 + 构建别名（零依赖，适配esbuild/tsc打包场景） #

适合不想改动各模块依赖配置的轻量场景，步骤如下：

• 先给common目录添加基础包声明，在common/下新建package.json：

{
  "name": "common",
  "version": "1.0.0",
  "main": "index.ts",
  "types": "index.ts"
}

• 修改根目录tsconfig.json，配置路径映射让TS识别别名，必须配置moduleResolution为node模式：

{
  "compilerOptions": {
    "baseUrl": ".",
    "moduleResolution": "node",
    "paths": {
      "common": ["./common/index.ts"]
    },
    // 原有配置（target、outDir、strict等）保持不变
  },
  "include": [
    "common/**/*.ts",
    // 补充所有Lambda模块的路径，例如"./service-user/**/*.ts", "./service-order/**/*.ts"
  ]
}

• 配置构建工具的别名映射，解决编译后路径不替换的问题：
  • 如果用esbuild打包Lambda（Node.js Lambda官方推荐的打包方式），在构建配置中添加alias字段：

  // esbuild配置示例
  require('esbuild').build({
    entryPoints: ['service-user/index.ts'],
    bundle: true,
    outfile: 'dist/service-user/index.js',
    platform: 'node',
    target: 'node18', // 对齐你的Lambda运行时版本
    alias: {
      common: './common/index.ts'
    }
  })
  

  • 如果直接用tsc编译输出不打包，安装tsc-alias作为编译后步骤，自动替换输出文件中的别名路径为相对路径即可。

方案2：npm本地文件依赖（符合Node原生规范，无额外构建配置） #

这是最贴近原生Node模块逻辑的方案，不需要额外配置TS路径和构建别名：

• 同方案1第一步，先在common/目录下创建基础package.json
• 进入每个需要引用common的Lambda模块目录，执行本地依赖安装命令：

# 以service-user模块为例，路径根据你实际目录层级调整
npm install ../../common

执行完成后，对应Lambda模块的package.json依赖中会自动添加"common": "file:../../common"，此时Node和TS会原生识别common包，直接写import { commonFunction } from 'common'不会触发类型报错，打包时所有构建工具都会自动识别本地文件依赖，不会出现Lambda运行时找不到模块的问题。

避坑提示：不要手动把common目录复制到node_modules下，该操作不符合npm依赖管理规范，执行npm install其他包时会被覆盖删除；也不要配置跨层级的全局绝对路径，会导致本地开发环境和Lambda运行环境路径不一致引发线上故障。

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