使用TSDX构建模块时浏览器出现模块解析错误的求助

开发者阿泽

2026-7-31

问题成因与解决方案

错误核心原因

错误导入类型声明文件：你导入的.d.ts是TypeScript类型声明文件，仅用于代码编辑器的类型校验，浏览器/Node.js无法执行这类文件，实际运行依赖的是编译后的.js文件。
导入路径不符合模块规范：第三方模块的导入应该直接使用包名（如module-name），而非module-name/dist/xxx这种路径写法。浏览器会把这种带dist的路径当作相对引用处理，但它又不符合相对引用必须以/、./或../开头的规则，因此抛出错误。
模块入口配置可能缺失：如果你的package.json没有正确配置模块入口字段，工具链无法自动解析包的正确文件路径，导致你不得不手动写dist路径。

解决步骤

1. 修正目标项目的导入语句

不要直接导入dist下的文件，也不要导入.d.ts。如果你的模块index.ts已经导出了需要的内容，直接用包名导入：

// 正确写法：从包的主入口导入
import { Class, Plugin1, Plugin2 } from 'module-name';

如果需要单独导入子模块（比如只导入Plugin1），需要先在模块的package.json中配置子路径导出，再按规范导入：

// 配置后可以这样导入（示例）
import { Plugin1 } from 'module-name/globals/plugins/plugin1';

2. 完善模块的package.json配置

确保你的模块package.json中包含以下关键字段，让工具链能正确识别入口文件：

{
  "name": "module-name",
  "main": "dist/module-name.cjs.production.min.js", // CommonJS入口
  "module": "dist/module-name.esm.js", // ES模块入口
  "types": "dist/index.d.ts", // 类型声明入口
  // 如果需要支持子路径导入，添加以下配置
  "exports": {
    ".": "./dist/module-name.esm.js",
    "./globals/plugins/plugin1": "./dist/globals/plugins/plugin1.js",
    "./globals/plugins/plugin2": "./dist/globals/plugins/plugin2.js"
  },
  "typesVersions": {
    "*": {
      "globals/plugins/plugin1": ["dist/globals/plugins/plugin1.d.ts"],
      "globals/plugins/plugin2": ["dist/globals/plugins/plugin2.d.ts"]
    }
  }
}

3. 检查TSDX的打包逻辑

默认TSDX会自动处理src下的文件打包，但如果你需要保留子目录结构的输出，确保tsconfig.json中的compilerOptions配置正确：

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist",
    "declaration": true,
    "declarationDir": "dist"
  }
}

如果需要自定义Rollup配置，可以在项目根目录创建tsdx.config.js，调整输出规则（比如保留模块结构）：

module.exports = {
  rollup(config, options) {
    // 自定义配置，比如保留子目录输出
    config.output.preserveModules = true;
    return config;
  },
};

额外说明

不要手动导入dist目录下的文件，npm包的设计就是通过package.json的入口字段让工具链自动解析正确的文件路径，手动写dist路径会破坏模块的封装性，也容易引发路径解析错误。
发布前可以在本地用npm link测试模块导入是否正常，避免发布后才发现问题。

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