开启@ts-check的JS文件中第三方库类型无法正确生效问题咨询

你当前的写法存在三个核心问题：

1. 写在普通.ts文件中的全局类型声明，默认不会被// @ts-check模式下的JS文件纳入类型解析上下文
2. 你声明的let Swiper = window.Swiper是该TS文件的局部变量，没有暴露到全局作用域，JS文件无法直接读取到对应的类型
3. 导入swiper类型时未取default导出，拿到的是模块对象而非构造函数类型，也会导致类型匹配错误

方案1：全局声明文件适配（推荐，所有JS文件都能复用类型） #

• 第一步：确认已安装swiper类型，swiper v8+官方自带类型，低版本需手动安装@types/swiper
• 第二步：在项目根目录或JS文件同级目录新建global.d.ts类型声明文件，写入以下代码：

declare global {
  interface Window {
    Swiper: typeof import('swiper').default;
  }
  // 直接声明全局变量Swiper的类型
  const Swiper: typeof import('swiper').default;
}
// 此行必加，将文件标记为模块避免全局声明报错
export {}

• 第三步：在项目根目录新增tsconfig.json配置，确保类型声明和JS文件都被纳入解析范围：

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "moduleResolution": "node",
    "target": "ESNext"
  },
  "include": [
    "./**/*.js",
    "global.d.ts"
  ]
}

配置完成后重启编辑器，所有JS文件中调用new Swiper()都会有正确的类型提示。

方案2：单文件JSDoc声明（无需配置全局，仅当前JS文件生效） #

如果不想新增配置文件，可以直接在需要使用Swiper的JS文件顶部通过JSDoc指定类型：

// @ts-check
/** @type {typeof import('swiper').default} */
const Swiper = window.Swiper;

// 后续调用自动匹配类型
new Swiper('.swiper-container', {
  // 配置项会自动触发类型提示和校验
})

这个方案同样适用于其他通过script标签引入的第三方库，只需要把import('swiper')替换为对应库的包名即可。

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