TypeScript开发Google Apps Script时ESLint no-undef报错解决方法

针对TypeScript + clasp 部署到Google Apps Script的项目，按以下步骤配置即可在不绕过no-undef变量校验逻辑的前提下，让ESLint正常识别Utilities、SpreadsheetApp这类内置全局对象，同时还能获得完整的API类型提示：

步骤1：安装官方类型声明依赖 #

GAS全量API的TypeScript类型包包含所有内置全局对象的声明，先在项目中安装该开发依赖：

npm install --save-dev @types/google-apps-script

步骤2：配置tsconfig.json加载全局类型 #

修改项目根目录的tsconfig.json，将GAS类型包加入编译选项的类型列表，TS编译器会自动加载所有全局声明，不需要在业务代码中手动导入：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "None",
    "strict": true,
    // 关键配置：加载GAS全局类型
    "types": ["google-apps-script"],
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./build"
  },
  "include": ["src/**/*.ts"]
}

注意：GAS运行时原生支持ES2020及以下语法，不需要额外打包转译，module设置为None即可适配clasp的部署逻辑。

步骤3：配置ESLint适配TS全局声明 #

TypeScript项目必须使用@typescript-eslint/parser作为ESLint解析器，确保ESLint能读取TS的类型声明信息，在ESLint配置文件（.eslintrc.js / .eslintrc.json等）中添加如下配置：

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": "./tsconfig.json",
    "ecmaVersion": 2020,
    "sourceType": "script"
  },
  "plugins": ["@typescript-eslint"],
  "rules": {
    // 关闭不识别TS类型的原生no-undef规则，替换为支持TS类型的同逻辑校验规则，未禁用变量未定义检查
    "no-undef": "off",
    "@typescript-eslint/no-undef": "error"
  }
}

如果你不想切换@typescript-eslint/no-undef规则，也可以直接在ESLint配置的globals字段中显式声明GAS全局对象为只读，这种方式不需要依赖TS类型解析，也会正常执行no-undef校验：

{
  "globals": {
    "Utilities": "readonly",
    "SpreadsheetApp": "readonly",
    "ScriptApp": "readonly",
    "UrlFetchApp": "readonly",
    "DocumentApp": "readonly",
    "FormApp": "readonly",
    "DriveApp": "readonly"
  }
}

这种手动声明的方式需要按需添加用到的全局对象，适合只调用少量GAS API的项目。

步骤4：配置生效 #

配置完成后重启ESLint服务（VS Code用户可通过命令面板执行ESLint: Restart ESLint Server），之前的'XXX' is not defined报错就会消失，编写代码时还能获得GAS API的自动补全、参数类型校验能力。

注意：不要在业务代码中手动import任何GAS内置对象，这些对象是GAS运行时全局注入的，手动import会导致线上运行报错，类型声明仅用于开发阶段的静态检查。

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