Vite中使用declare const仍无法消除TypeScript对define变量的报错

按照Vite官方文档建议，我在vite-env.d.ts里为define中定义的__WEB_GIT_DESCRIBE__和__META_GIT_DESCRIBE__添加了全局类型声明，但在Vue组件中使用这些变量时，TypeScript依然报错。虽然Vite能正确替换变量值，但类型检查始终不通过。

项目配置 #

vite.config.js #

const web_describe = execSync("git describe --dirty").toString().trim();
const meta_describe = execSync("git -C ./path/to/submodule describe --dirty").toString().trim();

export default defineConfig({
    // ...
    define: {
        __WEB_GIT_DESCRIBE__: JSON.stringify(web_describe),
        __META_GIT_DESCRIBE__: JSON.stringify(meta_describe),
    },
});

vite-env.d.ts #

// actual values in vite.config.js
// this is just to trick TypeScript into not flagging them in App.vue
declare const __WEB_GIT_DESCRIBE__: string;
declare const __META_GIT_DESCRIBE__: string;

通过git bisect排查后发现，当我在项目中添加tsconfig.json并仅修改strictNullChecks配置项后，TypeScript的报错消失了。现在想确认到底是哪个tsconfig配置项解决了这个问题。

核心解决配置项 #

问题本质是没有tsconfig.json时，TypeScript默认不会自动识别vite-env.d.ts这类全局声明文件，导致你的类型声明没被加载到Vue组件的类型检查中。结合你修改strictNullChecks后修复的情况，实际起作用的是以下关键配置：

• include：必须确保vite-env.d.ts被纳入TypeScript的编译范围。默认无tsconfig.json时，TypeScript的文件扫描规则不包含这类声明文件，添加tsconfig.json后需要明确指定：

{
  "include": ["src/**/*", "vite-env.d.ts"]
}

• strictNullChecks：你修改这个配置后问题修复，其实是因为添加tsconfig.json时，TypeScript启用了默认配置集，其中include规则被正确设置，而strictNullChecks的开启只是附带的——核心还是include确保了声明文件被加载。

• types（可选）：如果上述配置仍有问题，可以显式指定类型声明文件，强制TypeScript加载：

{
  "types": ["vite/client", "./vite-env.d.ts"]
}

验证步骤 #

1. 检查tsconfig.json的include字段，确认包含vite-env.d.ts
2. 确保vite-env.d.ts在项目根目录，或者在include覆盖的路径下
3. 重启TypeScript语言服务（比如VSCode中按Ctrl+Shift+P选择"TypeScript: Restart TS Server"）

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