求助：TypeScript无法识别typeRoots中的自定义声明文件（相对导入）

问题核心 #

你当前的声明文件是针对模块名handler编写的，但你使用的是相对路径导入（../build/handler.js）。TypeScript会将这种相对路径视为独立的文件模块，不会去typeRoots目录下匹配名为handler的模块声明，而是优先检查导入路径对应的.d.ts文件（也就是你看到的build/handler.d.ts）。

解决方案 #

方案1：修改声明文件的模块标识符，匹配相对导入路径

直接将声明文件中的模块名改为你实际导入的相对路径，让TypeScript关联到对应的声明：

修改server/typings/handler/index.d.ts内容：

declare module '../build/handler.js' {
    export const handler: (a: any) => void;
}

如果需要兼容不同层级的相对路径导入，可以使用通配符匹配：

declare module '*build/handler.js' {
    export const handler: (a: any) => void;
}

方案2：通过tsconfig.json的paths配置映射路径

在server/tsconfig.json的compilerOptions中添加paths配置，将相对导入路径映射到你的自定义声明文件：

"compilerOptions": {
    "typeRoots": [
        "../node_modules/@types",
        "./typings"
    ],
    "paths": {
        "../build/handler.js": ["./typings/handler/index.d.ts"]
    },
    // 保留其他原有配置
},
"include": [
    "./*.ts",
    "./typings/**/*.ts"
]

额外说明 #

typeRoots的作用是指定TypeScript查找第三方包类型（比如@types/node这类）的目录，不适用于相对路径导入的文件模块。对于相对路径导入，TypeScript的解析逻辑是：

1. 查找导入路径对应的.ts/.tsx文件
2. 查找导入路径对应的.d.ts文件
3. 如果都找不到，就会抛出“无声明文件”的错误

通过修改声明文件的模块标识符，让其匹配相对导入路径，就能让TypeScript正确关联到你的自定义声明。

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