Google Apps Script 中跨函数共享变量的正确方法有哪些

在Google Apps Script中，多个函数协同完成一项任务时，往往需要把某个函数产生的数据交给另一个函数继续处理。共享变量的方式选择不当，轻则导致取不到预期值，重则造成数据覆盖或并发写入异常。因此，理解不同共享机制的作用范围、生命周期和存储限制，是编写稳定脚本的基础。

一、通过全局变量实现函数间数据共享

全局变量是声明在所有函数之外的变量，脚本中任意函数都可以读取和修改它。这种方式不依赖外部存储，读写速度是所有共享方案中最快的，适合在单次脚本执行过程中传递配置项、中间计算结果等不需要长期保留的数据。

在声明全局变量时，通常使用var关键字放在脚本顶部。由于Google Apps Script基于JavaScript，全局变量会挂在当前脚本执行上下文中，函数内部可以直接通过变量名访问。例如，一个函数负责写入表格名称和最大行数，另一个函数负责读取并记录这些值，就可以借助全局对象完成。

// 定义全局变量，存储本次执行期间的共享配置
var sharedConfig = {
  sheetName: "数据表",
  maxRow: 100
};

function setConfig() {
  // 修改全局对象的属性
  sharedConfig.sheetName = "更新后的数据表";
  sharedConfig.maxRow = 200;
  Logger.log("全局变量已更新");
}

function useConfig() {
  // 读取全局对象中的共享数据
  Logger.log("当前表名：" + sharedConfig.sheetName);
  Logger.log("最大行数：" + sharedConfig.maxRow);
}

需要特别注意的是，全局变量只在当前一次脚本执行期间存在。一旦函数执行结束，脚本上下文释放，全局变量的值就会重置为初始状态。如果多个触发器几乎同时运行，它们各自拥有独立的执行上下文，对一个全局变量的修改并不会同步到另一次执行中，因此全局变量不适合用来保存需要跨执行、跨用户或跨文档长期存在的数据。

二、使用PropertiesService持久化共享数据

如果希望共享变量在多次脚本执行后仍然保留，可以使用PropertiesService。它类似于一个轻量级的键值存储服务，允许脚本把字符串数据保存到云端，下次运行脚本时再读取。PropertiesService提供三种作用范围：脚本属性对所有访问同一脚本的用户可见，用户属性只对当前用户可见，文档属性则绑定到某个具体的文档或表格。

PropertiesService适合保存用户偏好设置、资源ID、状态标记等体积较小的长期数据。写入时需要将所有值转换为字符串，读取后再根据实际需要转回数字、布尔值或对象。下面的示例演示如何保存、读取和删除脚本属性中的共享数据。

function saveSharedData() {
  // 获取脚本属性实例
  var scriptProperties = PropertiesService.getScriptProperties();
  // 键和值都必须是字符串类型
  scriptProperties.setProperty("userTheme", "dark");
  scriptProperties.setProperty("lastUpdateTime", new Date().getTime().toString());
  Logger.log("数据已保存到脚本属性");
}

function readSharedData() {
  var scriptProperties = PropertiesService.getScriptProperties();
  // 读取时得到字符串，需要转换类型
  var theme = scriptProperties.getProperty("userTheme");
  var updateTime = scriptProperties.getProperty("lastUpdateTime");
  Logger.log("用户主题：" + theme);
  Logger.log("最后更新时间：" + updateTime);
}

function deleteSharedData() {
  var scriptProperties = PropertiesService.getScriptProperties();
  // 删除单个属性
  scriptProperties.deleteProperty("userTheme");
  // 如果需要清空所有脚本属性，可取消下面一行的注释
  // scriptProperties.deleteAllProperties();
  Logger.log("指定数据已删除");
}

使用PropertiesService时需要注意容量限制：单个属性键值对的总大小不能超过9KB，所有脚本属性的总大小不能超过500KB。如果超出限制，写入操作可能会失败。因此它只适合存储小体积的配置数据和状态信息，不建议把大量计算结果或文件内容放入其中。此外，由于写入涉及云端存储，读写速度比全局变量慢，频繁调用时应当考虑缓存策略。

三、使用CacheService实现临时高速共享

CacheService是另一种共享数据方式，主要用于缓存那些不需要持久化、但短时间内会被多次访问的数据。它的读写性能优于PropertiesService，适合把一些重复计算的结果暂存起来，减少后续函数的执行时间。CacheService的数据带有过期时间，默认过期时间为600秒，开发者也可以在写入时自定义过期秒数。

例如，某个函数需要调用外部API获取数据，而另一个函数在随后不久也要使用相同数据，就可以把结果写入缓存。这样第二次读取时就不必再次请求外部服务。CacheService同样提供脚本缓存、用户缓存和文档缓存等作用范围，下面演示脚本缓存的基本操作。

function saveCacheData() {
  // 获取脚本缓存实例
  var cache = CacheService.getScriptCache();
  // 写入缓存，过期时间设置为300秒，即5分钟
  cache.put("tempResult", "计算得到的临时结果", 300);
  Logger.log("临时数据已存入缓存");
}

function readCacheData() {
  var cache = CacheService.getScriptCache();
  // 读取缓存，如果数据不存在或已过期，返回null
  var result = cache.get("tempResult");
  if (result != null) {
    Logger.log("读取到缓存数据：" + result);
  } else {
    Logger.log("缓存数据已过期或不存在");
  }
}

function deleteCacheData() {
  var cache = CacheService.getScriptCache();
  // 删除指定的缓存键
  cache.remove("tempResult");
  Logger.log("缓存数据已删除");
}

CacheService的容量同样有限：单个缓存项不能超过100KB，所有缓存项总大小不能超过5MB。由于缓存数据可能因为过期而被自动清除，开发者不能假设写入的数据一定会被读取到，必须在读取时判断返回值是否为null。它适合临时计算结果、短时间内的共享状态，不适合作为可靠的持久化存储。

四、不同共享方式的对比与常见错误

为了更直观地选择合适的方式，可以从持久化能力、读写速度和适用场景三个维度进行比较。全局变量速度最快，但不持久化；PropertiesService能够持久化，速度相对较慢；CacheService速度较快，但数据会过期。

在使用全局变量时，还有一个非常典型的错误需要避免：在函数内部重新声明同名变量。如果在函数中使用var、let或const再次声明同名变量，JavaScript会把这个变量视为该函数的局部变量，后续赋值只影响局部变量，全局变量并不会被修改。

var globalVar = 10;

function wrongUpdate() {
  // 错误：重新声明了同名变量，函数内部创建了局部变量
  var globalVar = 20;
  Logger.log(globalVar); // 输出20，但这只是局部变量的值
}

function checkGlobal() {
  Logger.log(globalVar); // 输出10，全局变量没有被修改
}

正确的做法是不加声明关键字，直接对全局变量进行赋值。这样JavaScript会沿作用域链向上查找已存在的全局变量，并修改它的值。

var globalVar = 10;

function correctUpdate() {
  // 正确：直接修改全局变量，不重新声明
  globalVar = 20;
  Logger.log(globalVar); // 输出20
}

function checkGlobal() {
  Logger.log(globalVar); // 输出20，全局变量已被修改
}

综合来看，如果数据只在当前执行流程中传递，优先使用全局变量；如果需要跨执行保存少量重要配置，选择PropertiesService；如果只是短时间缓存中间结果以提升性能，CacheService更为合适。合理控制变量作用域，避免不必要的全局状态，能够提高脚本的可维护性和执行稳定性。

Google_Apps_Script跨函数共享变量全局变量PropertiesServiceCacheService修改时间：2026-07-20 04:00:36