导入.d.ts文件引发Chrome运行时错误，疑遗漏TypeScript基础要点

看起来你踩了一个TypeScript新手常遇到的典型坑——.d.ts文件只是类型声明文件，完全不包含任何可执行的JavaScript代码。TypeScript编译器只会用它来做类型检查，根本不会把它转换成浏览器能运行的模块。所以当你写import { doSomething } from "exampleJsLibrary";时，TS编译时因为有.d.ts的存在不会报错，但浏览器拿到编译后的JS文件时，会真的去寻找exampleJsLibrary这个模块文件，自然找不到就报错了。

下面给你一步步解决的方案：

• 第一步：确认目标库的真实JS文件位置
  如果exampleJsLibrary是你自己写的模块，那你必须同时有对应的exampleJsLibrary.js（或.mjs）文件，.d.ts只是给TS提供类型提示的，不能替代实际代码。如果是第三方库，要确认它的JS文件是在本地node_modules里，还是需要通过CDN引入。

• 第二步：配置TS的路径映射（针对本地模块）
  打开你的tsconfig.json，添加baseUrl和paths配置，让TS知道导入的模块别名对应的真实文件路径。比如：

  {
    "compilerOptions": {
      "baseUrl": "./src", // 你的源码根目录
      "paths": {
        "exampleJsLibrary": ["./lib/exampleJsLibrary.js"] // 映射到真实JS文件的相对路径
      }
    }
  }
  

  这样TS编译后会把import "exampleJsLibrary"转换成正确的相对路径，浏览器就能找到对应的JS文件了。

• 第三步：处理第三方库的两种场景

  • 如果你用打包工具（比如Webpack、Vite）：只要你通过npm安装了库（以及对应的@types/xxx类型包），打包工具会自动处理模块导入，把第三方库的代码打包到最终的输出文件里，不需要额外配置，只要确保打包流程正常即可。
  • 如果你直接在浏览器中运行TS编译后的文件（没有打包工具）：你需要先在HTML里通过CDN引入第三方库的JS文件，比如：

    <script src="https://cdn.jsdelivr.net/npm/exampleJsLibrary@latest/dist/exampleJsLibrary.min.js"></script>
    

    然后在TS里通过声明全局模块来使用类型：

    declare module "exampleJsLibrary" {
      export function doSomething(): void;
    }
    

    或者如果库暴露了全局变量（比如window.exampleJsLibrary），直接用全局变量调用即可，不需要导入：

    (window as any).exampleJsLibrary.doSomething();
    

• 第四步：检查浏览器模块相关配置
  确保你的tsconfig.json里的module选项设置为浏览器支持的模块类型，比如ESNext或ES6，同时target设置为兼容你目标浏览器的版本。另外，编译后的JS文件必须在HTML里用type="module"引入：

  <script type="module" src="./dist/your-compiled-script.js"></script>
  

  这样浏览器才会按照ES模块的规则处理导入语句。

总结一下：.d.ts只是TS的类型“说明书”，不是代码本身，你必须让浏览器能找到对应的真实JS代码——要么通过路径映射指向本地文件，要么用打包工具整合第三方库，要么通过CDN引入全局库。

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