expo/envExpo 的 .env 环境变量加载机制——文件级联、变量展开与供应链安全防线【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo导读expo/env是 Expo 工具链中负责从.env文件加载环境变量并注入process.env的核心包支撑着npx expo start、npx expo export等所有 CLI 命令的.env体验。本篇基于 Expo 仓库中该包的源码与测试位于 packages/expo/env完整讲清它的文件优先级级联规则、变量展开语法、系统环境变量优先策略、针对供应链攻击的安全拦截机制以及它与 Expo CLI 的实际集成方式帮助你在项目中正确组织.env文件并理解每一个加载行为的底层实现。一、包定位与能力概述该包在 package.json 中声明的版本为2.4.2描述为 hydrate environment variables from .env files into process.env即把.env文件中的变量“注水”到process.env中。它支持标准 dotenv 格式含多模式文件、变量展开等约定运行时要求 Node.js20.12.0运行时依赖仅三个轻量包chalk日志着色、debug调试日志命名空间expo:env和getenv布尔值解析。整个实现由三个源码文件构成职责清晰文件职责src/index.ts公开 API文件列表生成、解析、加载到process.env、原值恢复、日志输出src/parse.ts单个.env文件内容解析与${VAR}变量展开src/constants.ts安全策略哪些键禁止从.env加载、哪些键仅允许出现在.local文件二、.env文件清单与优先级级联2.1 基于 NODE_ENV 的文件列表入口函数getEnvFilessrc/index.ts#L98-L138根据mode参数默认取process.env.NODE_ENV返回按优先级从高到低排列的文件名列表.env.${mode}.local // 最高优先级模式 个人覆盖 .env.local // 个人覆盖test 模式除外 .env.${mode} // 模式专属 .env // 最低优先级全局默认各模式下的具体清单由 测试文件 逐一断言development.env.development.local→.env.local→.env.development→.envproduction.env.production.local→.env.local→.env.production→.envtest.env.test.local→.env.test→.env刻意不含.env.local源码注释说明原因测试预期对所有人产出一致结果不应被本机个人配置污染未设置NODE_ENV时打印错误提示并退化为仅加载.env.local和.envsrc/index.ts#L115-L120常量KNOWN_MODES [development, test, production]定义了“约定模式”。当NODE_ENV是其它值如staging时getEnvFiles会打印告警NODE_ENVstaging is non-conventional and might cause development code to run in production. Use development, test, or production instead. Continuing with non-conventional mode告警不阻断——流程继续以该模式运行getEnvFiles({ silent: true })可将其降级为 debug 日志供嵌入方自行决定噪声级别。2.2 级联合并语义parseEnvFiles把文件列表**反转为“最低优先级最先解析”**的顺序遍历src/index.ts#L170-L214后解析的同名键覆盖先解析的值从而实现“高优先级文件胜出”。测试用例cascades env files (development)验证了完整级联当六个文件都定义FOO时最终取值为最高优先级文件.env.development.local中的dev-local。读取过程中对常见文件系统错误做了静默降级仅 debug 日志不抛错ENOENT文件不存在跳过EISDIR同名路径是目录跳过EACCES无读取权限跳过。只有解析内容本身的错误才会向上抛出。三、解析与变量展开parse.ts 的实现细节3.1 基础解析单文件解析委托给 Node 内置的node:utilparseEnvsrc/parse.ts#L7-L13。这里有一个值得注意的兼容处理源码注释指出在部分 Node 20.x 版本中解析出的键未被正确 trim因此手动对每个键执行key.trim()再输出。3.2 变量展开dotenv-expand 兼容expand函数实现了与 dotenv-expand 兼容的${VAR}替换核心正则与算法移植自 dotenv-expand11src/parse.ts#L28-L75。语法能力基础引用PORT${HOST_PORT}——若HOST_PORT存在于源环境则展开为对应值默认值${VAR:-fallback}——变量缺失时取fallback且默认值本身若以$开头可再展开最多三层嵌套转义\$100输出字面量$100最终统一执行replace(/\\\$/g, $)跨文件引用展开发生在所有文件合并之后“executed as final step”见 src/index.ts#L161 注释因此高优先级文件可以引用低优先级文件中定义的变量防递归TEST_EXPAND${TEST_EXPAND}这类自引用不会死循环展开为空字符串——测试expands variables safely without recursive loop专门覆盖了该场景。测试expands variables from cascading env files (development)展示了跨文件展开的完整链路.env定义TEST_VALUE_ENVtest.env.development用TEST_INTERMEDIATE${TEST_VALUE_ENV}引用最终得到test。四、加载到 process.env不覆盖语义与加载标记4.1 两层 APIparse 不改动系统环境load 才改动parseProjectEnv(projectRoot, options)只解析、不写入process.env返回{ env, files, sensitiveLoadedKeys }loadProjectEnv(projectRoot, options)在parse基础上把结果写入系统环境。若mode为development/production会先调用setNodeEnv把NODE_ENV设置为该模式再加载src/index.ts#L327-L339测试sets NODE_ENV before loading project env files验证了.env.production中即使写了NODE_ENVdevelopment也不会生效因为写入遵循“不覆盖”规则。4.2 三条关键规则系统环境变量优先.env永不覆盖loadEnvFiles中只有当process.env[key]未定义时才写入文件值src/index.ts#L289-L297并 debug 输出FOO is already defined and IS NOT overwritten。这意味着 shell 中export FOOshell后运行npx expo start.env里的FOO不会生效——这是刻意的安全设计。幂等标记__EXPO_ENV_LOADED首次加载完成后loadEnvFiles会把本次实际写入的键名序列化为 JSON 写入process.env.__EXPO_ENV_LOADED常量LOADED_ENV_NAME。后续任何未加force的加载调用直接短路返回{ result: skipped }防止 CLI 内部多处调用造成重复变更。force: true可绕过该标记重新加载但依然遵守“不覆盖”规则测试mutates without overwriting after previous mutation when using force验证。原值备份与恢复rememberOriginal借助挂在globalThis上的WeakMap以Symbol.for(expo/env.originalEnvBackup.v1)为键记录每个被修改键的加载前值且跨模块副本共享——即使依赖树中同时存在两份expo/envhoisted nested备份状态也一致测试shares backup state across multiple installations via globalThis专门模拟了该场景。基于此getOriginalEnv()/getOriginalEnvValue(key)2.3.0 版本新增见 CHANGELOG.md可以构造出“剥离.env影响”的纯净环境快照用于child_process.spawn的env参数——例如让子进程解析 SDK 工具路径时不被项目.env干扰。对于继承自父进程的 dotenv 值子进程拿不到父进程内存中的备份则通过继承来的__EXPO_ENV_LOADED标记识别并剔除。五、安全模型被拦截的键与仅限本地的键这是expo/env区别于普通 dotenv 库的核心设计策略代码集中在 src/constants.ts。它把.env文件视为“可能由他人提交的项目内容”供应链视角分两级防护5.1 硬性拦截键isIgnoredEnvKey以下键在任何.env*文件中都不允许出现一旦检出parseProjectEnv直接抛出错误并拒绝加载整个文件集合而不是跳过单键Expo 内部键__EXPO_ENV_LOADED、__EXPO_CONFIG_MODE、EXPO_NO_DOTENV、EXPO_UNSAFE_DOTENV_KEYS。其中__EXPO_CONFIG_MODE是特例——即使被列入EXPO_UNSAFE_DOTENV_KEYS豁免名单也会被拦截isUnsafeAllowedEnvKey显式排除它测试keeps __EXPO_CONFIG_MODE blocked when the unsafe list includes it验证动态加载器Linux 的LD_PRELOAD、LD_LIBRARY_PATH、LD_AUDIT及所有LD_*macOS 的DYLD_*全系——防止篡改动态链接行为Node/Bun 行为NODE_PATH、NODE_OPTIONS、NODE_EXTRA_CA_CERTS、NODE_TLS_REJECT_UNAUTHORIZED、NODE_COMPILE_CACHE、BUN_RUNTIME_TRANSPILER_CACHE_PATH等Shell 启动钩子BASH_ENV、ENV、ZDOTDIR、PROMPT_COMMAND、SHELLOPTS等——防止在 CLI shell 出时注入命令git/ssh/gpg 参数GIT_SSH_COMMAND、GIT_ASKPASS等多语言运行时选项PerlPERL5OPT、PythonPYTHONPATH、PYTHONSTARTUP等、RubyRUBYOPT等、Java_JAVA_OPTIONS、CLASSPATH等用户身份与路径基础HOME、PATH、SHELL、USER、TEMP系、XDG_*目录、Windows 的SYSTEMROOT包管理器根NPM_CONFIG_REGISTRY、NPM_CONFIG_USERCONFIG、YARN_REGISTRY、PNPM_HOME、BUN_INSTALL等——源码注释明确指出这些变量没有正当的按项目.env用例各自有.npmrc/.yarnrc.yml/.bunfig.toml机制而恶意值在 CLI 调用 npm/yarn 时即构成供应链 RCE。测试throws on package-manager registry/install vars even in .local files验证了即使在.local文件中也拦截。错误信息会逐文件列出违规键并提示用EXPO_UNSAFE_DOTENV_KEYS显式豁免见 5.3。5.2 仅限.local的键isLocalEnvKey这类键属于“按开发者/按机器”的配置ANDROID_HOME、JAVA_HOME、DEVELOPER_DIR、NDK_ROOT、代理变量HTTPS_PROXY、FASTLANE_PASSWORD等凭据、REACT_NATIVE_OVERRIDE_HERMES_DIR等规则是出现在已提交的.env、.env.mode中 → 抛错拒绝加载防止恶意项目把开发者的 Android SDK / JDK 路径重定向到攻击者目录出现在.env.local/.env.mode.local中 → 允许且该键会进入sensitiveLoadedKeys在日志中高亮提醒见第六节。注意即使.env.local里已经覆盖了同一键已提交文件中的违规设置仍会导致整体加载失败——测试throws if a committed file sets a local-only key even when .local also sets it验证了这一点。设计意图是让开发者修复提交文件的错误配置而不是被本地覆盖“掩盖”。5.3 两个逃生舱环境变量EXPO_NO_DOTENV1完全禁用.env加载。isEnabled()通过getenv的boolish解析任何真值1、true都生效生效后getEnvFiles返回空列表、parseEnvFiles/loadProjectEnv返回空结果仅在debug(expo:env)日志留痕。EXPO_UNSAFE_DOTENV_KEYSkey1,key2逗号分隔的豁免名单允许被拦截/仅限本地的键从任意.env文件加载isIgnoredEnvKey、isLocalEnvKey均先查此名单。源码特意在模块加载时一次性读取该值不动态重读避免运行期被.env自身的加载逻辑“自解锁”。测试honors EXPO_UNSAFE_DOTENV_KEYS to allow a local-only key in any file演示了让ANDROID_HOME出现在.env中的显式豁免方式。六、加载日志CLI 终端里那些灰字从哪来logLoadedEnvsrc/index.ts#L416-L441产出你在运行npx expo start时看到的三行输出由 logLoadedEnv 测试 精确断言env: load .env.local .env.development .env ← 灰色实际加载的文件按优先级 env: export FOO BAR ← 灰色实际写入 process.env 的键 env: export (sensitive) ANDROID_HOME JAVA_HOME ← 黄色来自 .local 文件的敏感键行为细节force或silent模式不打印skipped结果只打印env: export展示父进程已加载的键没有新键时完全静默。黄色“sensitive”行的价值在于它把“哪些敏感值正在影响本次构建”显式暴露给用户与第五节的拦截策略形成闭环。七、与 Expo CLI 的集成loadEnvFiles 与 reloadEnvFilesCLI 侧的接入点在 packages/expo/cli/src/utils/nodeEnv.ts展示了expo/env在真实命令流程中的用法首次加载loadEnvFilesL74-L106先setNodeEnv(mode)同步设置NODE_ENV、BABEL_ENV和globalThis.__DEV__再调用env.loadProjectEnv(projectRoot, params)。silent参数会与shouldReduceLogs()或运算——非交互环境自动降级日志。加载成功后向2g事件总线发射env:load事件含模式、文件、键供诊断/telemetry 使用。热重载reloadEnvFilesL112-L146开发服务监视.env文件变化时走这条路径——用parseProjectEnv不直接 mutate重新解析再配合模块级prevEnvKeys追踪“哪些键是我自己写进去的”只覆盖自有键、不覆盖用户后来在 shell 中手动 export 的值实现安全的“改了.env立即生效”。模式传递getConfigEnvModeL53-L63优先消费父工具通过内部变量__EXPO_CONFIG_MODE传递的模式缺失时回退到“EAS Build 环境视为production否则development”——与consumeConfigEnvMode读取并删除该变量、非法值直接抛错配套。CLI 还有两处消费了“原值恢复”能力src/utils/env.ts 与 src/api/user/UserSettings.ts 都导入getOriginalEnvValue用于在需要“真实系统值”而非项目.env值时读取单个键。八、实践指南如何组织项目的 .env 文件结合本文源码分析推荐的目录组织如下以典型 Expo 应用为例my-expo-app/ ├── .env # 提交到 git所有环境共享的默认值如 API 基址 ├── .env.local # gitignore个人覆盖本机数据库地址、个人密钥 ├── .env.development # 提交开发模式专属 ├── .env.development.local# gitignore开发 个人 └── .env.production # 提交生产构建专属不含任何个人凭据配套约定与验证要点把.env*.local加入.gitignore——isLocalEnvKey策略正是依赖“.local不入库”的约定才成立凭据放.local不放已提交文件如FASTLANE_PASSWORD、ANDROID_HOME这类键出现在.env或.env.production会直接报错阻断变量引用用${VAR}或${VAR:-default}注意引用可跨文件解析合并后统一展开但自引用会被展开为空shell 中 export 的值永远胜过.env文件调试“为什么我改了 .env 没生效”时优先检查 shell 环境CI 场景test模式不读.env.local保证测试结果与个人机器解耦如需完全禁用 dotenv如让 CI 只认 CI 注入的变量设EXPO_NO_DOTENV1误触拦截时错误信息会指明具体文件与键名修复方式是移动/删除违规键确有需要才用EXPO_UNSAFE_DOTENV_KEYS显式豁免且__EXPO_CONFIG_MODE不可被豁免。九、遗留 API 与版本说明为向后兼容src/index.ts#L443-L524 保留了三个带deprecated标记的旧 APIget(projectRoot)带模块级 memo建议改用parseProjectEnv、load(projectRoot)建议改用loadProjectEnv、getFiles(mode)建议改用getEnvFiles。旧 API 内部同样遵守EXPO_NO_DOTENV与“不覆盖”规则且load直接 mutateprocess.env源码注释说明避免创建新对象是为兼容 Bun。适用的前提与限制本包为纯 Node 侧工具无原生代码运行要求 Node ≥ 20.12它只负责开发/构建工具链的环境加载应用运行时JS bundle 内读取process.env的行为受 Expo 打包时常量替换机制约束不在本包范围内。十、小结expo/env用一个不到千行的实现把“dotenv 文件加载”从简单的键值解析升级为一套有明确安全边界的机制优先级级联getEnvFiles 反序覆盖、dotenv-expand 兼容展开parse.ts的递归安全插值、系统环境优先 幂等加载标记__EXPO_ENV_LOADED与原值备份、以及双层键策略硬拦截isIgnoredEnvKey 仅限本地isLocalEnvKey。Expo CLI 通过loadEnvFiles/reloadEnvFiles将其接入启动与热重载流程。理解以上机制后你可以准确预测任何.env配置在npx expo命令中的实际行为并在遇到“值不生效”或“拒绝加载”报错时快速定位根因。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考