如何在SvelteKit项目中全局配置TypeScript类型免逐文件导入

SvelteKit v1.0.0-next.354

• 项目内所有stores、components、API路由文件必须手动编写导入语句引入自定义类型，否则VS Code会抛出TypeScript错误，常规导入写法如下：

import type { MyType } from '$lib/types'

• 曾尝试将自定义类写入app.d.ts的App命名空间下，代码如下，但是方案不生效：

declare namespace App{
  export class Aircraft{
    // 类属性、方法定义
  }
}

• 项目文件量增长到数十个后，逐文件手动导入类型的操作重复繁琐，需要实现一处配置、全项目直接使用自定义类型无需单独导入的效果。

首先明确app.d.ts中App命名空间的作用：它是SvelteKit预留用于扩展框架内置类型（比如服务端Locals、页面PageData等框架原生类型）的专用命名空间，不会自动将写入的普通自定义类型注册为全局类型，所以之前的写法不生效。

可以按以下步骤配置全局类型：

1. 在src目录下新建global.d.ts文件作为全局类型声明文件

   注意：如果直接在该文件内写类型声明，不要在文件顶部添加任何import/export语句，一旦存在导入导出语法，该文件会被TypeScript识别为普通模块，声明的类型不会全局生效。

2. 在文件内直接声明需要全局使用的类型、类，不需要套任何命名空间，示例：

   // src/global.d.ts
   declare interface MyType {
     id: number
     name: string
   }
   
   declare class Aircraft {
     id: string
     model: string
     takeoff(): void
     // 其余类属性、方法定义
   }
   

3. 检查根目录tsconfig.json的include配置，确保覆盖了src下所有.d.ts文件，SvelteKit默认配置已经满足要求，如果之前修改过该配置，需要补上对应规则：

   {
     "include": ["src/**/*.d.ts", "src/**/*.js", "src/**/*.ts", "src/**/*.svelte"]
   }
   

配置完成后重启VS Code的TypeScript服务（按Ctrl+Shift+P/Cmd+Shift+P，选择「TypeScript: Restart TS Server」），所有类型即可在全项目直接使用，无需单独导入。

如果你已经把所有自定义类型集中写在了$lib/types.ts这类模块文件里，不想迁移到global.d.ts，可以用以下两种方式实现全局可用：

• 方式一：在global.d.ts顶部添加三斜杠引用指令，直接引入类型文件

  // src/global.d.ts
  /// <reference path="./lib/types.ts" />
  

• 方式二：如果类型文件存在多层导出结构，可以在global.d.ts内手动挂载到全局

  // src/global.d.ts
  import type * as CustomTypes from '$lib/types'
  declare global {
    export type MyType = CustomTypes.MyType
    export class Aircraft extends CustomTypes.Aircraft {}
    // 其余需要全局暴露的类型依次声明
  }
  // 末尾必须加空导出，让TS识别该文件为模块
  export {}
  

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