如何让VSCode在Vue3 TS项目中识别grecaptcha全局变量

我通过npm init vue@latest命令搭建了Vue.js 3 TypeScript项目，计划从零开始接入reCaptcha v2，不安装vue3-recaptcha-v2这类第三方封装支持库。

我没有手动定义grecaptcha对象，而是安装了开发依赖npm i -D @types/grecaptcha，理论上安装完成后即可直接使用全局变量grecaptcha，但当前VSCode无法识别该全局变量。

问题截图：

项目自动生成的配置文件如下：

• vite.config.js

import vueI18n from "@intlify/vite-plugin-vue-i18n";
import vue from "@vitejs/plugin-vue";
import { fileURLToPath, URL } from "url";
import { defineConfig } from "vite";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue(), vueI18n({ useVueI18nImportName: true })],
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
});

• tsconfig.json

{
  "extends": "@vue/tsconfig/tsconfig.web.json",
  "include": ["env.d.ts", "src/**/*", "src/**/*.vue"],
  "compilerOptions": {
    "baseUrl": ".",
    "types": ["element-plus/global", "@intlify/vite-plugin-vue-i18n/client"],
    "paths": {
      "@/*": ["./src/*"]
    }
  },

  "references": [
    {
      "path": "./tsconfig.config.json"
    }
  ]
}

• tsconfig.config.json

{
  "extends": "@vue/tsconfig/tsconfig.node.json",
  "include": ["vite.config.*", "vitest.config.*", "cypress.config.*"],
  "compilerOptions": {
    "composite": true,
    "types": ["node"]
  }
}

上述文件均为执行npm init vue@latest时自动初始化生成，需要配置后让VSCode正确识别来自DefinitelyTyped的全局变量类型。

问题原因 #

tsconfig.json中显式配置了compilerOptions.types字段，一旦手动设置该字段，TypeScript只会加载数组中指定的类型包，不会自动扫描node_modules/@types目录下的其他全局类型定义，因此安装的@types/grecaptcha未被加载，最终导致VSCode无法识别grecaptcha全局变量。

修复步骤 #

1. 修改根目录下的tsconfig.json，将grecaptcha加入compilerOptions.types数组：

   {
     "extends": "@vue/tsconfig/tsconfig.web.json",
     "include": ["env.d.ts", "src/**/*", "src/**/*.vue"],
     "compilerOptions": {
       "baseUrl": ".",
       "types": ["element-plus/global", "@intlify/vite-plugin-vue-i18n/client", "grecaptcha"],
       "paths": {
         "@/*": ["./src/*"]
       }
     },
     "references": [
       {
         "path": "./tsconfig.config.json"
       }
     ]
   }
   

2. 重启VSCode的TypeScript服务让配置生效：
   • 按快捷键Ctrl+Shift+P（macOS系统按Cmd+Shift+P）调出命令面板
   • 搜索并执行TypeScript: Restart TS Server

备选方案（上述修改不生效时使用） #

打开项目中已存在的全局类型声明文件env.d.ts，在文件顶部添加三斜线类型引用指令：

/// <reference types="grecaptcha" />

保存文件后同样重启TS服务即可。

注意：grecaptcha是reCaptcha脚本加载完成后挂载在window上的全局变量，不要在业务代码中手动写import语句导入，否则会出现运行时错误。

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