TypeScript中如何合并相对路径导入的自定义类型与自动生成类型

我刚碰到过几乎一模一样的问题！你遇到的两个核心问题：一是tsc生成的声明文件保留了相对路径导入导致dist里找不到类型文件，二是合并声明时出现的TS2439错误，本质是因为在ambient模块声明里不能用相对路径引用其他模块。下面给你几个可行的解决方案：

先理解错误原因 #

你生成的index.d.ts里的declare module 'abuseipdb'属于ambient模块声明（用来描述全局可用的模块类型），TypeScript明确禁止在这种声明里使用相对路径导入其他模块——因为ambient模块是全局上下文的，相对路径在这里没有有效的模块解析上下文，所以才会抛出Import or export declaration in an ambient module declaration cannot reference module through relative module name错误。

解决方案1：手动合并类型（快速临时解决） #

最简单的方法就是把你的自定义UmbressOptions接口直接内联到生成的index.d.ts里，替换掉相对路径的导入：

修改后的dist/index.d.ts：

/// <reference types="ioredis" />
/// <reference types="express" />
/// <reference types="pug" />
declare module 'abuseipdb' {
  import { Redis } from 'ioredis'

  // 直接把自定义类型放在这里
  export interface UmbressOptions {
    isProxyTrusted?: boolean
    rateLimiter?: {
      enabled?: boolean
      requests?: number
      per?: number
      banFor?: number
    }
    clearQueueAfterBan?: boolean
    logs?: boolean
    whitelist?: Array<string>
    blacklist?: Array<string>
    checkSuspiciousAddresses?: {
      enabled?: boolean
      token?: string
      action?: 'block' | 'check'
      banFor?: number
      cookieTtl?: 1
    }
    advancedClientChallenging?: {
      enabled: boolean
      cookieTtl?: number
      content?: string
      userAgentsWhitelist?: RegExp
      cache?: 'redis'
      cacheHost?: string
      cachePort?: number
    }
  }

  export function checkAddress(ip: string, options: UmbressOptions, redis: Redis, jailKey: string): Promise<void>
}

这样所有类型都在同一个文件里，不会有路径找不到的问题，也解决了TS2439错误。

解决方案2：用工具自动合并声明文件（长期维护推荐） #

如果你的项目类型很多，手动合并太麻烦，推荐用dts-bundle-generator这个工具，它专门用来把TS项目的所有依赖声明合并成单个文件：

1. 安装依赖：

npm install --save-dev dts-bundle-generator

2. 在package.json里添加打包脚本：

{
  "scripts": {
    "build": "tsc && npm run build:dts",
    "build:dts": "dts-bundle-generator -o dist/index.d.ts src/index.ts"
  }
}

3. 运行npm run build，工具会自动把你代码里用到的所有自定义类型（包括UmbressOptions）合并到dist/index.d.ts里，完全消除相对路径导入的问题，生成的文件会直接包含所有需要的类型定义。

解决方案3：调整TS配置与代码结构（从根源避免问题） #

如果你想让tsc本身生成更干净的声明文件，可以调整项目结构和TS配置：

1. 把你的自定义类型放在src/types/index.ts（barrel文件）里，然后在tsconfig.json里配置路径映射：

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"]
    },
    "declaration": true,
    "declarationDir": "./dist",
    "outDir": "./dist",
    "isolatedModules": false
  }
}

2. 在代码里用绝对路径导入类型：

import { UmbressOptions } from '@/types'

3. 然后用tsc-alias工具把生成的声明文件里的绝对路径替换成相对路径：

npm install --save-dev tsc-alias

在package.json脚本里添加：

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

这样生成的声明文件里的路径会被正确替换，同时也不会出现ambient模块的导入错误。

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