不注册@types的前提下，能否在无类型包内添加声明文件供引用项目识别？

你完全可以将类型声明文件直接放在被引入的第三方包内，无需在每个使用项目单独声明。导入项目无法识别类型，通常是包的配置或声明文件写法不符合规范导致，按以下步骤排查即可：

1. 配置包的package.json指向声明文件 #

这是最常见的失败原因，TypeScript默认会读取包package.json中的types（或typings）字段定位类型声明文件。
示例包结构：

@org/client/
├── package.json
├── index.js       # 包的运行时入口文件
└── index.d.ts     # 你编写的类型声明文件

在package.json中添加对应配置：

{
  "name": "@org/client",
  "version": "1.0.0",
  "main": "./index.js",
  "types": "./index.d.ts", // 关键配置，声明类型文件的路径
  "//": "其他配置项..."
}

如果你的包支持子路径导入（比如import utils from '@org/client/utils'），需要额外配置exports字段同时关联类型和运行时入口：

{
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "default": "./index.js"
    },
    "./utils": {
      "types": "./utils.d.ts",
      "default": "./utils.js"
    }
  }
}

2. 修正声明文件的导出语法 #

声明文件的导出语法需要和包实际的运行时导出规则匹配，否则会出现类型识别异常：

• 如果包是CommonJS规范的module.exports = client导出，对应声明文件可以用export = client
• 如果包是ES Module规范的export default client导出，对应声明文件需要用export default client
• 如果包是具名导出，对应声明文件直接写export const xxx: XxxType即可

符合规范的声明文件示例：

// index.d.ts
declare module "@org/client" {
  interface Client {
    request: (url: string, options?: Record<string, any>) => Promise<unknown>;
    // 补充其他方法、属性的类型定义
  }
  const client: Client;
  // 根据包的实际导出方式二选一
  // export = client; // 适配CommonJS导出
  export default client; // 适配ES Module默认导出
}

3. 排除缓存与使用方配置问题 #

如果包的配置和声明文件都正确，仍无法识别类型，按以下步骤排查：

• 重新安装依赖：删除使用方项目的node_modules文件夹，重新安装修改后的包，避免旧版本缓存
• 重启TypeScript服务：在IDE中重启TypeScript语言服务，以VS Code为例，按下Ctrl+Shift+P（Mac为Cmd+Shift+P），搜索并执行「重启TypeScript语言服务」
• 检查使用方tsconfig配置：确认使用方项目的tsconfig.json没有设置"types": []限制类型包范围，也没有在exclude字段中添加对应包的过滤规则
• 清除构建缓存：删除使用方项目的tsconfig.tsbuildinfo等缓存文件后重试

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