Posting 环境变量指南：用 `.env` 文件与 `${VAR}` 语法构建多环境 API 工作流

Posting 环境变量指南：用.env文件与${VAR}语法构建多环境 API 工作流

【免费下载链接】postingThe modern API client that lives in your terminal.项目地址: https://gitcode.com/gh_mirrors/po/posting

Posting 是运行在终端里的现代 API 客户端，它内置了一套轻量的变量系统：你可以在 URL、请求头、请求体等输入区域中使用${VARIABLE_NAME}或$VARIABLE_NAME语法引用变量，这些变量会在请求发出前被替换成实际值。本指南将完整讲解变量的定义、加载、分层覆盖、宿主环境变量开关，以及如何在.env文件中注入环境特定的 Posting 配置，并辅以 variables.py、__main__.py等源码实现来阐明底层原理，帮助你在 dev / prod 等多套环境下复用同一份请求集合。

变量语法：两种引用形式

在 Posting 的任何输入字段和文本区域中，都可以通过下面两种语法引用变量：

${VARIABLE_NAME} $VARIABLE_NAME

例如 URL 栏中的https://${BASE_URL}/users、请求头中的Authorization: Bearer $API_KEY都是合法写法。变量会在请求发出时被替换为实际值，因此你可以把主机名、端口、密钥、路径前缀等经常变化的部分抽成变量，让同一份请求在不同环境下复用。

从源码看，变量识别由 variables.py 中的正则_VARIABLES_PATTERN驱动，它同时支持带花括号与不带花括号两种形式，并且变量名遵循[a-zA-Z_]\w*的命名规则（即以字母或下划线开头，后面可跟字母、数字、下划线）。

一个值得注意的细节是转义：连续两个$可以转义变量引用。tests/test_variables.py中对应的参数化用例验证了这一点，例如"Hello, $$foo $bar"只会解析出$bar，而$${hello}不会被当作变量；"$"、"$$"、"${}"这些空引用同样不会被解析。

变量的来源：.env文件与--env选项

变量存放在.env文件中，并通过启动参数--env加载。一个典型的.env文件长这样：

# file: dev.env API_KEY="dev-api-key" ENV_NAME="dev" BASE_URL="https://${ENV_NAME}.example.com"

注意BASE_URL的值内部引用了另一个变量ENV_NAME，这说明.env文件中定义的变量之间也支持互相引用，Posting 会按 dotenv 的规则解析这些嵌套引用。

要让这些变量在界面中可用，启动时加载即可：

posting --env dev.env

--env选项（等价短选项为-e）在main.py 中被定义为multiple=True，这意味着它可以被指定多次，从而加载多个.env文件：

posting --env dev.env --env shared.env

多次加载的合并在 load_variables 中实现：所有文件按命令行顺序依次读取并合并进同一个字典，后出现的文件会覆盖先出现的同名键。这正是多环境分层模型的基础——把公共变量放到shared.env，把环境特有变量放到各自的dev.env/prod.env，再用"先公共、后特定"的顺序加载即可。

自动加载posting.env

如果没有提供任何--env选项，Posting 会自动加载当前工作目录下的posting.env文件（如果存在的话）。这一逻辑同样在 make_posting 中体现：

# if env empty then load current directory posting.env file if it exists if not env and os.path.exists("posting.env"): env = ("posting.env",)

也就是说，对于把 Posting 当作项目开发工具的开发者，可以把posting.env放进项目根目录并纳入版本控制，实现"进入项目目录、启动 Posting 即生效"的无感配置体验。

宿主环境变量：use_host_environment开关

出于安全与可复现性的考虑，Posting 默认只使用通过--env显式加载的.env文件中定义的变量，宿主机器上已有的环境变量不会被自动引入。

如果你希望允许使用宿主环境变量（即未在任何.env文件中定义、但存在于操作系统环境中的变量），需要显式打开开关，两种方式任选其一：

# 方式一：配置文件 config.yaml use_host_environment: true

# 方式二：环境变量 POSTING_USE_HOST_ENVIRONMENT=true

在 config.py 中，use_host_environment的默认值为false；开启后，load_variables 会把os.environ中的全部变量并入可用变量集，并且注意合并顺序是.env变量在前、宿主环境变量在后，因此宿主环境变量会覆盖同名.env变量。建议仅在可信的本地开发环境中开启此选项。

实战：shared / dev / prod 多环境模型

假设你正在测试一个同时存在于dev和prod两套环境的 API。两套环境共享部分公共变量，但在密钥、域名上又有很大差异。最自然的建模方式是：一个shared.env存放公共变量，dev.env与prod.env分别存放环境特有变量。

# file: shared.env API_PATH="/api/v1" ENV_NAME="shared" # file: dev.env API_KEY="dev-api-key" ENV_NAME="dev" BASE_URL="https://${ENV_NAME}.example.com" # file: prod.env API_KEY="prod-api-key" ENV_NAME="prod" BASE_URL="https://${ENV_NAME}.example.com"

在dev环境工作时，按"公共在前、特定在后"的顺序加载：

posting --env shared.env --env dev.env

此时shared.env的变量全部生效，随后dev.env的变量再加载进来；由于ENV_NAME同时出现在两个文件中，后指定的dev.env中的值会覆盖shared.env中的值（最终为dev），BASE_URL也就相应地解析为https://dev.example.com。切换到 prod 环境时，只需把命令换成posting --env shared.env --env prod.env，同一份请求集合即可无缝复用。

热更新：无需重启即可生效

编辑.env文件不需要重启 Posting。你完全可以一边在编辑器里修改dev.env，一边让 Posting 保持运行——保存后变量即会重新加载。这一行为由配置项watch_env_files（默认true）控制，见 config.py：启用后 Posting 会监听环境文件的变化并自动重新加载，这正是"改完即用"的底层机制。

环境特定配置：把POSTING_*配置写进.env文件

Posting 的所有配置项都可以通过环境变量指定（规则是配置名加POSTING_前缀，嵌套配置用__分隔，例如POSTING_HEADING__VISIBLE，详见 configuration.md）。既然.env文件本质上是环境变量文件，你自然可以把环境特定的配置写进.env文件里，随环境一并加载。

例如，如果你想在 prod 环境中使用浅色主题（作为"当前在生产环境"的视觉提醒），可以在prod.env中加入：

# file: prod.env POSTING_THEME="solarized-light"

这样加载prod.env时主题就会随之切换，而 dev 环境不受影响。

需要特别强调配置优先级：配置文件（config.yaml）优先于环境变量，环境变量优先于.env文件。也就是说，如果你在.env文件和config.yaml中都设置了同一个值，最终生效的是config.yaml中的值。这条优先级在 config.py 的settings_customise_sources中有直接体现——当配置文件存在时，YAML 源被插入到环境变量源与 dotenv 源之前。

源码级原理：变量如何被识别、替换与提示

要深入理解这套变量系统，可以沿着三条代码路径阅读：

1. 变量加载与存储。核心在 variables.py：load_variables使用dotenv_values逐个读取.env文件合并成字典，缓存到全局的SharedVariables单例（variables.py）中，后续通过get_variables()读取。测试 test_load_env_file_dialog.py 验证了加载文件后get_variables()能拿到文件中的键值。

2. 文本中的变量定位。find_variables（variables.py）负责从任意文本中找出所有变量引用及其起止位置，并带有lru_cache缓存；variable_range_at_cursor则用于判断光标是否落在某个变量内部。这些函数是编辑体验（如自动补全、值预览）的基础。仓库示例环境文件 tests/sample-envs/sample_base.env 展示了最朴素的键值写法（POST_ID=1、USER_ID=2等），可直接作为参考模板。

3. 编辑器内的变量自动补全。在输入区域中，当光标处于变量引用内部时，Posting 会弹出以当前已加载变量为候选的补全列表。这一能力由 variable_autocomplete.py 实现：候选列表默认取自get_variables()（形如$VARIABLE_NAME），选中后仅替换变量名部分而不破坏其余文本。补全 UI 相关的行为可以在命令面板触发"Load environment file"对话框（实现在 load_env_file_dialog.py）时看到，其路径自动补全会优先展示.env、*.env、.env.*命名的文件。

4. 未定义变量的处理。如果请求中引用了不存在的变量，会抛出SubstitutionError（定义于 variables.py），避免静默地把未定义引用当作普通字符串发送，从而提前暴露拼写错误或漏配的环境文件。

小结

Posting 的变量系统由".env文件 +--env选项 +use_host_environment开关"三块构成：.env文件负责按环境隔离变量，--env支持多次指定以叠加文件、后者覆盖前者，而宿主环境变量默认关闭、按需开启。再结合"所有配置都能写成POSTING_*环境变量"这一设计，你可以在dev、prod等多套环境间仅通过切换启动参数就完成变量与配置的整体切换，且编辑即时生效、无需重启。配合命令面板中的"Load environment file"对话框和输入框内的变量自动补全，整套流程在纯键盘驱动下即可高效运转。

【免费下载链接】postingThe modern API client that lives in your terminal.项目地址: https://gitcode.com/gh_mirrors/po/posting