发布含ambient模块声明的npm包能否被消费方自动识别？

可以发布包含ambient模块声明的npm包，你遇到的问题是TypeScript对非@types包的默认类型加载规则导致的，按以下步骤配置即可实现用户无需额外配置自动识别：

核心原因 #

TypeScript默认仅会自动加载@types/*包、用户项目源码目录下的.d.ts中的全局ambient声明。你的包不属于@types范围，所以哪怕配置了types字段，你根目录下index.d.ts里的通配符模块声明默认不会全局生效，只有当这个.d.ts文件被显式加载时才会生效。而用户使用时都是直接导入子路径（如import xxx from 'pkg-with-many-assets/xxx.svg'），不会主动导入包根路径，所以声明文件没有被加载，自然不生效。

你观察到的把@types/simple-icons的声明放到simple-icons包根目录不生效的现象，也符合这个规则：@types域下的包会被TS特殊处理，自动加载内部的全局声明，而普通npm包默认没有这个待遇，必须通过配置触发声明文件的加载。

推荐解决方案（无需用户额外配置） #

1. 保持你现有的index.d.ts内容不变，确保里面没有任何顶层的import/export语句（否则会被识别为模块，内部的declare module不会全局生效）
2. 在你包的package.json中添加typesVersions配置，示例如下：

{
  "name": "pkg-with-many-assets",
  "version": "1.0.0",
  "types": "./index.d.ts",
  "typesVersions": {
    "*": {
      "*": ["./index.d.ts"]
    }
  },
  // 其余配置保持不变，比如exports、main等
  "exports": {
    "./*": "./*"
  }
}

这个配置的作用是：无论用户导入你包下的任意子路径，TypeScript都会统一使用你根目录的index.d.ts作为对应路径的类型声明文件。用户导入子路径时会自动加载这个文件，里面的通配符ambient模块声明就会生效。

你可以在测试项目中执行npx tsc --traceResolution，搜索你导入的子路径，查看TypeScript是否正确指向了你包的index.d.ts文件，确认配置生效。

旧版TS兼容备选方案 #

如果需要兼容不支持typesVersions的特别旧版TypeScript，可以在包的README中补充可选配置说明，让用户在项目tsconfig.json的include字段中添加你的包路径：

{
  "compilerOptions": {},
  "include": ["src", "node_modules/pkg-with-many-assets"]
}

绝大多数场景下typesVersions方案已经可以覆盖所有主流TS版本，不需要用户做任何额外配置。

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