导入openapi-client-axios生成的OpenAPI类型时出现TS2307找不到模块错误

算力阿峰

2026-11-7

Vue+TypeScript 导入openapi-client-axios生成类型的问题定位与修复

问题背景

技术栈：Vue + TypeScript
类型生成流程：后端产出符合OpenAPI规范的api.json文件，执行typegen api.json > proto.d.ts生成客户端类型定义，存放路径为src/types/proto.d.ts，需在src/rigging/api.ts中导入导出的RestClient类型

实际项目目录结构：

项目根目录/
├─ vue.config.js
├─ tsconfig.json
└─ src/
   ├─ main.ts
   ├─ App.vue
   ├─ rigging/
   │  └─ api.ts
   └─ types/
      └─ proto.d.ts

已尝试的无效操作与报错表现：
- 先后尝试配置@types别名、不同层级相对路径、带/不带.d.ts后缀的导入写法，其中import { RestClient } from '@types';触发TS2307: Cannot find module '@types' or its corresponding type declarations.错误，其余写法也触发模块找不到、后缀非法的同类报错
- 尝试将proto.d.ts重命名为index.d.ts、调整文件存放层级，仍无法被TypeScript识别
- 已将tsconfig.json的typeRoots配置为["./types"]，问题未解决

项目扫描逻辑：只要文件在tsconfig.json的include字段覆盖范围内，TypeScript就会自动扫描该文件的内容，无需额外配置
.d.ts文件的两种状态：
- 全局声明态：文件内没有顶层export/import语句，声明的类型会直接作为全局类型存在，业务代码无需导入即可使用
- 模块态：文件内存在顶层export/import语句，会被识别为独立模块，必须通过明确的路径导入才能使用其中导出的类型，无法自动全局生效
typeRoots配置的边界：该配置仅用于指定第三方@types作用域包的查找路径，不承担用户自定义业务类型的查找功能，将业务类型目录配置到typeRoots中不会让该目录下的文件成为可直接导入的模块
@types作用域的特殊逻辑：只有node_modules/@types目录、或者typeRoots配置路径下、命名符合@types/[包名]规范的目录，才会被识别为@types作用域模块，项目内自定义的src/types目录不属于这个作用域，无法直接通过@types作为路径前缀导入

修正tsconfig.json的错误配置
- 将之前错配的typeRoots: ["./types"]恢复为默认的["node_modules/@types"]，避免干扰第三方类型包的正常查找
- 确认tsconfig.json的include字段包含"src/**/*"，保证src目录下所有ts、d.ts文件都能被项目扫描到
配置路径别名简化导入路径（可选但推荐）
- 在tsconfig.json的compilerOptions中添加路径映射配置：
```
{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```
- 同步在构建配置（vue.config.js/webpack配置/vite.config.ts）中配置对应的路径别名解析，保证构建阶段能正确识别路径
使用正确的导入语法
- 不要携带.d.ts后缀，不要使用@types作为路径前缀，在src/rigging/api.ts中使用如下导入写法：
```
// 别名导入写法
import type { RestClient } from '@/types/proto';
// 相对路径导入写法（无需配置别名即可生效）
import type { RestClient } from '../types/proto';
```
- 采用import type语法单独导入类型，适配TS的isolatedModules配置要求，避免类型被错误打包到业务代码中
可选的全局类型配置（不推荐）
- 如果不希望在业务代码中手动导入类型，可去掉proto.d.ts文件中所有顶层的export语句，将类型改为全局声明。该方式会破坏类型的模块边界，不适合客户端接口类型这类需要强约束的场景。

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