无法在Cloud Functions参数中使用process.env值的问题排查

我花了一小时排查函数故障，将问题简化为如下示例代码：

import {onDocumentCreated} from 'firebase-functions/v2/firestore';

export const myfunction = onDocumentCreated(
    `users/{uid}/${process.env.TEST_KEY}/{id}`,
    (event) => {
        console.log(process.env.TEST_KEY);
    }
);

（.env文件中配置有TEST_KEY=data）

可以看到，当用模板字符串把环境变量嵌入Firestore触发器的监听路径时，触发器无法正常生效。但如果把路径硬编码为固定值：

import {onDocumentCreated} from 'firebase-functions/v2/firestore';

export const myfunction = onDocumentCreated(
    `users/{uid}/data/{id}`,
    (event) => {
        console.log(process.env.TEST_KEY);
    }
);

此时功能完全正常，向Firestore添加文档时控制台能正常输出data——也就是说，process.env.TEST_KEY能在函数内部正常解析，但就是无法在触发器路径的模板字符串中生效，这是为什么？

原因分析 #

这是Firebase Functions v2的设计限制导致的：

Firebase Functions的部署流程和运行流程是完全分离的：

• 部署阶段：Firebase CLI会静态分析你的函数代码，提取触发器的配置信息（包括Firestore监听路径），并将这些配置同步到Firebase后台。此时process.env环境变量还未被注入——因为环境变量是函数运行时才会加载的依赖，部署环境无法获取到这些值，所以CLI无法解析模板字符串里的process.env.TEST_KEY，最终导致触发器配置失败。
• 运行阶段：当函数被Firestore事件触发时，函数实例会加载配置的环境变量，此时函数内部的process.env.TEST_KEY就能正常读取到值。

社区相关讨论也明确了这一点：Firebase Functions v2不支持在触发器路径中使用动态值（比如环境变量），触发器路径必须是静态可解析的字符串，否则部署工具无法正确配置监听规则。

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