第 43 章 环境变量与系统信息

本章导读

env 模块薄但关键（全套 API 五个函数，一小时学完，用一辈子）：它是配置的最外层（环境变量——容器时代的第一配置入口：12-Factor 应用的配置全靠它）与宿主信息的第一查询口（系统名、版本、机器标识）。取值有两条入口，语义各异：xrtEnvGet 返回拥有式副本（NULL = 不存在——副本隔离了后续环境变化，比裸 getenv 安全）；xrtEnvLookup 双通道（返回 bool + 出参带回拥有式副本）——且有个关键细分：false 才是真失败（如编码问题），"变量不存在"是成功状态、输出置空；Get 的 NULL 则两种情况不可区分。这些入口共同回答三态问题：存在有值 / 存在为空 / 不存在——"不存在"不是错误。本章除 API 外，重点讲环境变量作为配置层的适用边界——这是配置架构决策的一部分——哪些配置该放环境变量、哪些坚决不该。

43.1引入

部署同一份镜像到开发/预发/生产——配置怎么区分？文件路径每个环境不同、构建时写死等于为每个环境出一次包。环境变量是答案：DATABASE_URL、LOG_LEVEL、LISTEN_PORT 在编排层（compose/k8s）按环境注入，镜像本身零环境差异——"一次构建、处处运行"的配置支柱。

但环境变量的边界也要认清：它是扁平的字符串映射——结构化配置（嵌套对象、数组）硬塞进环境变量要发明编码约定（A_B_C=1 式的扁平化），约定一多就成灾难；长度限制（部分平台的历史包袱）与类型全字符串也在给复杂配置添堵。业界共识的分界（12-Factor 与多数工程实践的交汇点）：环境差异的少量开关（地址、级别、开关）进环境变量；业务配置的主体（复杂结构、频繁变更）进配置文件（第 32 章 JSON/XLON）——启动时环境变量覆盖文件默认值的"双层配置"是标准形态（第 38 章日志级别"环境变量读取"正是这个模式）。

43.2概念

读取与三态语义

环境变量读取的核心问题是三态：存在有值 / 存在但为空 / 不存在。Get 的 NULL 与 Lookup 的"成功+空输出"都是"缺失"的显式答案——绝不把"不存在"伪装成空字符串（空串可能是合法配置值）。variants 范例的 missing=ok 断言演示：缺失走默认值路径，与"读到值"是两条被验证的路径。

写入与进程环境

xrtEnvSet 修改本进程的环境块——写入真实生效（不是进程内模拟表），因此后续创建的子进程会继承（第 53 章进程创建的环境继承机制）；xrtEnvRemove 删除。写环境变量是影响全局的操作——多线程下的环境块操作非线程安全（POSIX 的历史包袱），纪律是只在启动单线程阶段写，运行期只读。Set/Remove 返回 bool 报告成败——Windows 与 POSIX 的 putenv 语义差异已由实现抹平。

系统信息查询（运行期的平台通道）

宿主信息一族：操作系统名与版本（日志诊断头、平台分支的运行时判断——编译期分支用第 8 章 XRT_FEATURE_ 宏，运行期才知的用这里）、CPU/内存概况（容量规划的自检报告）、机器标识（分布式节点注册时上报"我是谁"）。这类查询的共同形态：只读、启动时查一次缓存复用（除了内存余量这类动态信息按需再查）。

配置分层的位置

三层各司其职：环境变量管"这个部署环境什么样"、配置文件管"这个业务怎么配"、命令行管"这次运行临时改什么"。优先级从低到高：文件 < 环境 < 命令行——启动装配代码按这个顺序逐层覆盖。

43.3示例

完整程序：三态读取与默认值

来自仓库范例 examples/environment/variants/main.c：

 */

#include <stdio.h>
#include <xrt.h>

int main(void)
{
	str sValue = NULL;

	/* 不存在的变量：成功返回 + 空输出。 */
	if ( xrtEnvLookup("XRT_DEFINITELY_MISSING", &sValue) ) {
		printf("missing=ok\n");
	}
	xrtFree(sValue);
	sValue = NULL;

	/* 存在的变量：拥有式副本。 */
	(void)xrtEnvSet("XRT_LOOKUP_EXAMPLE", "hello");
	if ( xrtEnvLookup("XRT_LOOKUP_EXAMPLE", &sValue) && sValue != NULL ) {
		printf("present=%s\n", sValue);
	}
	xrtFree(sValue);
	(void)xrtEnvRemove("XRT_LOOKUP_EXAMPLE");
	return 0;
}

刚才发生了什么。 ① 对一个未设置的变量名读取：返回 false → 程序走默认值路径，输出 missing=ok——缺失不是错误，是三态之一。② 对已设置的变量读取：拿到视图、解析使用——present=hello。③ 本例演示的是拥有式路径：Get 返回副本、用完 xrtFree——即使环境随后被改，这份字符串不受影响；需要"存在性先行"的判断用 Lookup——两条入口按调用姿态选择。④ 未注入直接跑也全 ok：程序对"配没配"两者都健壮——默认值策略的意义。

完整程序：系统信息报告

来自 examples/system/environment/main.c：

 */

#include <stdio.h>

#include <xrt.h>



int main(void)
{
	str sValue;

	/* 设置：真实进程环境（子进程会继承）。 */
	if ( !xrtEnvSet("XRT_ENVIRONMENT_EXAMPLE", "hello") ) {
		return 1;
	}

	


	 */
	sValue = xrtEnvGet("XRT_ENVIRONMENT_EXAMPLE");
	if ( sValue == NULL ) {
		return 2;
	}
	printf("value=%s\n", sValue);
	xrtFree(sValue);

	/* 收尾删除，范例不留下全局副作用。 */
	return xrtEnvRemove("XRT_ENVIRONMENT_EXAMPLE") ? 0 : 3;
}

刚才发生了什么。 ① xrtEnvSet 写入真实进程环境——子进程会继承（第 53 章）；Windows 与 POSIX 的 putenv 语义差异已被实现抹平（返回 bool 统一报告成败）。② xrtEnvGet 读回拥有式副本——之后即使环境被改，这份字符串不受影响；用完 xrtFree。③ xrtEnvRemove 删除——三步闭环（Set/Get/Remove）就是环境管理的最小完整集。系统信息查询（概念区提到的系统名/版本/机器标识）在同一头文件家族，用于诊断头与节点注册上报。

43.4契约

• 三态语义：存在有值/存在为空/不存在——读取 API 双通道返回，缺失走显式默认值。
• 写时机：环境写入只在启动单线程阶段；运行期只读（线程安全 + 视图稳定的双重要求）。
• 子进程继承：本进程环境修改影响后续创建的子进程（第 53 章继承语义）。
• 配置分层：文件默认 < 环境覆盖 < 命令行最高——环境变量只放"环境差异开关"。
• 平台分支双通道：编译期差异用特性宏（第 8 章）、运行期差异用本模块查询——不混用。

从示例到工程：环境变量的三个宿主

容器化部署（环境变量的主场）：镜像零环境差异，DATABASE_URL/LOG_LEVEL/PORT 由编排层按环境注入——12-Factor 配置原则的落地形态；健康检查地址、密钥引用路径也常走这里。开发调试：本地跑服务时用环境变量临时覆盖（LOG_LEVEL=DEBUG ./app）——比改配置文件快且不留痕；shell 的临时前缀语法正是为此而生。子进程环境构造：第 53 章创建子进程前 xrtEnvSet 定制子进程环境（给它专属的配置视图）——父进程改环境、子进程继承生效。三宿主共同印证"环境变量 = 环境差异开关"的定位——超出这个范围的配置需求都该去文件层。

一个运维观：环境即接口

部署描述（compose/k8s 的 env 段）是应用的对外接口——它声明"这个服务需要哪些环境差异输入"。接口就要有文档与校验：启动时枚举全部预期的环境变量并打印装配结果（LOG_LEVEL=INFO (env) 还是 (default)）——"配置装配日志"是排障第一站；缺失必需变量（如生产环境没给 DATABASE_URL）快速失败并明确报错，不要带着空值跑起来再在第一个请求上炸。这两条加上坑区的"运行期不写"，就是环境变量从"能用"到"可运维"的三级台阶。

配置装配的完整图景

把本章放进配置全景：启动装配读三层（文件默认 < 环境覆盖 < 命令行最高），装配结果进值树（第 31 章）供全程序消费；装配日志打印最终值与来源；必需项校验快速失败。这个装配器是第 36 章管线的"配置环节"完全体——练习二的挑战版就是它。装配一次、全局只读：配置的热更新（运行期改配置）走"新值树原子替换 + 通知"的路径（第 31 章三宿主），而不是运行期写环境变量——两层纪律再次呼应。

常见错误

/* 十几个业务参数全走环境变量——编排层成了配置文件的劣化版 */
int timeout = env_int("SVC_TIMEOUT_MS", 3000);
int retry = env_int("SVC_RETRY", 3);
str endpoint = env_str("SVC_ENDPOINT", "...");
/* ... 还有二十个 ... */

/* 配置主体在文件（结构化值树），环境变量只留环境开关 */
xvalue* pCfg = xrtJsonParse(read_file("config.json"), NULL);
int timeout = cfg_int(pCfg, "timeout", 3000);           /* 文件默认 */
if ( env_has("SVC_TIMEOUT_MS") ) {                       /* 环境覆盖 */
	timeout = env_int_override("SVC_TIMEOUT_MS");
}

void handle_config_reload(void)
{
	xrtEnvSet(XRT_STR_LITERAL("APP_MODE"), ...);   /* 运行期写——并发读线程 UB */
}

/* 环境写入集中在 main 开头（单线程阶段） */
int main(void)
{
	apply_env_overrides();          /* 唯一写入点 */
	/* 之后全程只读 */
}

编程练习

小结