TypeScript 实现类静态泛型配置初始化并支持跨文件属性自动补全

原代码抛出TS2302错误的核心逻辑是：类级别的泛型参数T 绑定给类的实例使用，静态成员属于类本身，完全无法访问类的实例泛型作用域，因此直接在静态属性上标注T 属于非法语法。

以下两个方案均可实现两项核心要求：

• 支持单次初始化配置，可在运行时拦截重复初始化
• 跨文件访问配置属性时获得精准自动补全，无any 类型丢失问题

方案1：运行时拦截 + 类型自动收窄（推荐） #

利用TS的断言函数实现编译期类型绑定，同时在运行时禁止重复初始化：

// theme.ts 配置定义文件
let initialized = false;

class ThemeExample {
    // 初始占位类型
    static theme!: unknown;
    static init<T extends object>(theme: T): asserts this is { theme: T } {
        if (initialized) {
            throw new Error('主题配置仅允许初始化一次');
        }
        // 运行时存储配置实例
        ThemeExample.theme = theme;
        initialized = true;
    }
}

// 全局仅执行一次初始化
ThemeExample.init({
    hello: 'hi',
    button: {
        primaryColor: '#165DFF',
        borderRadius: 4
    }
})

// 提取初始化时传入的完整配置结构类型
type Theme = Parameters<typeof ThemeExample.init>[0];
// 导出时收窄静态属性类型，让外部调用时获得精准补全
export default ThemeExample as { theme: Theme };

跨文件使用时：

// 其他业务文件导入后访问
import ThemeExample from './theme'

// 自动补全可提示hello、button、button.primaryColor等所有属性
ThemeExample.theme.button.primaryColor

方案2：模块类型扩展实现 #

通过declare 做编译期的类型声明，不影响运行时逻辑：

// theme.ts
class ThemeExample {
    static theme!: object;
    static init<T extends object>(theme: T) {
        ThemeExample.theme = theme;
    }
}

// 单次初始化
ThemeExample.init({
    hello: 'hi',
    button: { primaryColor: '#165DFF' }
})

// 提取实际配置类型，扩展类的静态属性类型
type ActualTheme = Parameters<typeof ThemeExample.init>[0];
declare class ThemeExample {
    static theme: ActualTheme;
}

export default ThemeExample

• 泛型仅绑定在静态init 方法上，TS会在编译期自动推理出init调用时传入参数的完整结构，不需要提前手写配置接口
• 由于ES模块本身是单例加载的，配置仅会在模块首次导入时初始化一次，搭配运行时的拦截逻辑可完全避免重复初始化的问题
• 通过类型收窄把静态theme 属性的类型从通用占位值替换为实际传入的配置结构，跨文件导入时TS会自动追踪该类型，实现精准的属性自动补全

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