环境变量

Egern 支持为脚本、小组件和模块配置环境变量（env）。环境变量以键值对形式传递，脚本中可通过 ctx.env 访问，使得同一脚本在不同场景下可以灵活配置而无需修改代码。

基本用法

在脚本中定义

所有五种脚本类型均支持 env 字段：

scriptings:
  - generic:
      name: "my-script"
      script_url: "https://example.com/scripts/my-script.js"
      env:
        API_KEY: "your_api_key"
        API_URL: "https://api.example.com"
  - http_request:
      name: "modify-header"
      match: "^https://api\\.example\\.com/"
      script_url: "https://example.com/scripts/modify-header.js"
      env:
        TOKEN: "my-secret-token"
  - schedule:
      name: "daily-checkin"
      cron: "0 8 * * *"
      script_url: "https://example.com/scripts/checkin.js"
      env:
        USERNAME: "user123"

在小组件中定义

widgets:
  - name: "weather-widget"
    env:
      CITY: "Shanghai"
      UNIT: "celsius"

在模块引用中定义

modules:
  - url: "https://example.com/module.yaml"
    enabled: true
    env:
      API_KEY: "your_api_key"
      REGION: "cn"

在脚本中访问

环境变量在脚本运行时通过 ctx.env 以键值对形式访问：

export default async function(ctx) {
  const apiKey = ctx.env.API_KEY;
  const apiUrl = ctx.env.API_URL;

  const resp = await ctx.http.get(apiUrl + '/data', {
    headers: { 'Authorization': 'Bearer ' + apiKey }
  });
  const data = await resp.json();
  console.log(data);
}

优先级与合并

当同一键名存在于多个层级时，优先级从高到低为：

模块 > 小组件 > 脚本

即模块级别的 env 会覆盖小组件级别的同名变量，小组件级别的 env 会覆盖脚本级别的同名变量。

合并示例

假设有以下配置：

scriptings:
  - generic:
      name: "my-widget"
      script_url: "https://example.com/scripts/widget.js"
      env:
        COLOR: "blue"
        TIMEOUT: "10"
        MODE: "default"

widgets:
  - name: "my-widget"
    env:
      COLOR: "red"
      REGION: "Asia"

脚本实际收到的 ctx.env 为：

键	值	来源
COLOR	"red"	小组件（覆盖了脚本的 "blue"）
TIMEOUT	"10"	脚本
MODE	"default"	脚本
REGION	"Asia"	小组件

如果该小组件来自模块，且模块引用中定义了 env：

modules:
  - url: "https://example.com/module.yaml"
    env:
      COLOR: "green"
      LANG: "zh"

则最终 ctx.env 为：

键	值	来源
COLOR	"green"	模块（最高优先级）
TIMEOUT	"10"	脚本
MODE	"default"	脚本
REGION	"Asia"	小组件
LANG	"zh"	模块

适用场景

• API 密钥管理： 将 API Key 等敏感信息放在 env 中，脚本文件可公开分享而不泄露密钥。
• 多实例复用： 同一脚本配合不同 env 创建多个小组件，例如同一天气脚本显示不同城市。
• 模块参数化： 模块作者提供通用功能，用户通过 env 传入个性化参数。
• 环境区分： 通过 env 区分开发/生产环境的 API 地址。

# 同一脚本，不同环境变量，显示不同城市天气
scriptings:
  - generic:
      name: "weather"
      script_url: "https://example.com/scripts/weather.js"

widgets:
  - name: "weather-sh"
    script_name: "weather"
    env:
      CITY: "Shanghai"
  - name: "weather-bj"
    script_name: "weather"
    env:
      CITY: "Beijing"