三星 S25 `.env` 配置失效故障排查：变量名大小写引发的静默失败，真机实测破防了

背景与适用场景

这篇文章主要面向以下场景：

• 在三星 S25 系列（含 S25、S25+、S25 Ultra、S25 Edge 等机型）上运行的 Android 应用，使用 `.env` 文件管理环境变量
• 使用 dotenv、react-native-config 或类似库加载环境配置
• 遇到”明明代码没问题，但变量值一直是 null 或空字符串”的诡异情况
• 项目在 Pixel、iPhone 开发环境跑得好好的，一到三星设备上就翻车

如果你刚好遇到上面任何一种情况，这篇文章应该能帮你省下好几个小时的排查时间。

一、`.env` 文件与环境变量加载机制简介

在正式排查前，有必要先简单回顾一下 `.env` 是怎么被加载的，理解清楚机制才能定位问题根源。

`.env` 文件本质上就是一个纯文本配置文件，每行一个键值对，格式通常是：

API_KEY=abc123
DEBUG_MODE=true
BaseUrl=https://api.example.com

加载流程一般是这样的：

1. 应用启动时，dotenv 类库读取 `.env` 文件
2. 按行解析，遇到 `=` 分割 key 和 value
3. 将 key/value 写入进程的内存中（或者通过反射注入到 BuildConfig）
4. 业务代码通过 System.getenv()、process.env 或框架封装的方法读取

在桌面端、服务器端（Linux/macOS），环境变量名严格区分大小写是行业共识：API_KEY 和 api_key 是两个完全不同的变量。这个特性在 Node.js、Python、Java、Go 等主流语言中无一例外。

所以一旦你的 `.env` 文件里写的是 api_key，而代码里引用的是 API_KEY，按照标准行为，读取到的就是 null，并且没有任何报错——这就是所谓的”静默失败”。

二、为什么在三星 S25 上特别容易踩这个坑

按理说大小写敏感是跨平台的通用规则，为什么三星 S25 会成为重灾区？这就要说到 Android 文件系统的一些历史包袱了。

2.1 Android 文件系统的大小写敏感性

Android 底层基于 Linux，理论上文件系统是大小写敏感的。但 Samsung One UI 在某些版本（特别是 One UI 5 到 One UI 7 之间）的实现中，对 /sdcard、/storage/emulated/0 这类用户可见存储路径做了兼容处理，导致：

• 同一个目录下，config.env 和 Config.env 可能被视为同一个文件
• dotenv 库在遍历文件、读取配置时，可能因为文件名归一化导致逻辑分支走错
• 当你的 `.env` 文件名是大驼峰 Config.env，而构建脚本里写的是 config.env 时，可能读取到意料之外的内容

2.2 三星 Knox 与企业配置的影响

S25 系列普遍预装了 Samsung Knox 安全框架。在企业管控模式（Work Profile）下，Knox 会对应用沙盒内的文件读写做一层包装，导致 dotenv 库对文件路径的解析出现差异。这种情况下，变量值取不到的现象会仅在三星设备上复现，Pixel、小米、OPPO 上一切正常。

2.3 One UI 8 的新变化

2026 年推送的 One UI 8 进一步收紧了文件权限管理，部分原本能读取的路径被默认收紧。如果你刚升级到 One UI 8 后突然发现原本能用的 `.env` 读不到了，多半和这个改动有关。有开发者反馈，升级后连 adb shell 查看应用私有目录的权限都变严格了，排查难度直接拉满。

三、复现步骤：最小化 demo 验证

为了确认你遇到的就是这个”大小写静默失败”问题，可以按下面的最小步骤复现。

3.1 准备测试工程

以 React Native + react-native-config 为例：

// .env 文件内容（注意大小写）
api_key=sk-test-123456
BaseUrl=https://api.example.com

代码里这样引用：

import Config from 'react-native-config';

console.log('API_KEY =', Config.API_KEY);   // 输出 undefined
console.log('BASE_URL =', Config.BASE_URL); // 输出 undefined

3.2 在三星 S25 上跑一遍

• 真机：S25 / S25 Ultra，One UI 7 或 8
• 命令：npx react-native run-android --deviceId=<三星设备ID>
• 观察：日志里两个变量都是 undefined，没有任何 warning 或 error

3.3 对照实验

把同一份代码推到 Pixel 9 或小米 15 上跑，变量值能正常读取。这基本就可以确诊是三星设备的兼容问题了。

四、排查命令与诊断方法

如果不能确定是不是大小写引起的，可以按以下顺序排查：

4.1 检查文件实际内容

进入三星设备的 shell：

adb -s <三星设备ID> shell
run-as com.your.package.name  # 假设应用可调试
cat /data/data/com.your.package.name/files/.env

确认文件里实际存储的 key 是什么大小写。

4.2 打印所有加载到的环境变量

在 dotenv 加载完成后，加一行调试代码：

// Node.js / React Native 通用
require('dotenv').config({ debug: true });

debug: true 会让 dotenv 把”成功加载了哪些 key、哪些 key 被忽略”全部打印到控制台。这一步能直接看到你的 key 是否被正确解析。

4.3 用 adb 直接验证环境变量

adb -s <三星设备ID> shell
run-as com.your.package.name env | grep -i api

这个命令会列出应用进程内所有环境变量，grep -i 忽略大小写匹配，能帮你快速定位变量是否存在、实际名称是什么。

4.4 检查构建产物中的 BuildConfig

# 在项目根目录执行
grep -r "API_KEY" android/app/build/generated/source/buildConfig/

如果 BuildConfig 里没有生成对应的字段，说明 react-native-config 在构建阶段就没能正确解析 `.env` 文件。

五、不同库的配置差异对比

不同加载库对大小写的处理策略不完全一样，这也是很多人困惑的点。下面用表格对比主流方案：

关键差异点：

• dotenv 在运行时读取文件，大小写不一致直接返回 undefined
• react-native-config 在构建时解析，大小写不一致会导致 BuildConfig 字段缺失，编译期可能不报错，但运行时拿到的是 null
• react-native-dotenv 是 Babel 插件，构建时做静态替换，大小写不一致直接编译报错（这个反而最容易发现）

六、修复方案：正确配置与代码示例

6.1 统一命名规范（推荐）

在 `.env` 文件中统一使用大写 + 下划线命名：

# .env 文件（推荐写法）
API_KEY=sk-test-123456
BASE_URL=https://api.example.com
DEBUG_MODE=true

代码中引用：

import Config from 'react-native-config';

console.log('API_KEY =', Config.API_KEY);   // 正常输出
console.log('BASE_URL =', Config.BASE_URL); // 正常输出

6.2 使用映射表兜底

如果你无法修改 `.env` 文件（比如它是第三方提供的），可以在代码里做一层映射：

// config.js
import Config from 'react-native-config';

const envMap = {
  API_KEY: Config.API_KEY || Config.api_key || '',
  BASE_URL: Config.BASE_URL || Config.BaseUrl || '',
};

export default envMap;

这样无论 `.env` 里是哪种大小写，都能正确读取。

6.3 构建脚本统一处理

在 package.json 的构建脚本里，用脚本统一转换 `.env` 文件：

# scripts/normalize-env.sh
#!/bin/bash
# 将 .env 中所有 key 转为大写
awk -F= '{print toupper($1) "=" $2}' .env > .env.tmp && mv .env.tmp .env

6.4 原生 Android 方案

如果你用的是原生 Android + Kotlin/Java，推荐用 BuildConfig 方式：

// app/build.gradle
buildTypes {
    debug {
        buildConfigField "String", "API_KEY", "\"${project.env.API_KEY}\""
    }

七、避坑指南：三星设备环境变量配置的 5 个建议

八、常见问题 FAQ

Q1：为什么我的 `.env` 文件在 Pixel 上正常，在三星 S25 上就读不到？
A：大概率是文件系统大小写敏感性的差异。三星 One UI 对用户存储路径做了兼容处理，可能导致 dotenv 库在遍历文件时行为不一致。建议统一使用全大写命名，并在三星真机上做验证。

Q2：升级 One UI 8 后 `.env` 突然失效了，怎么办？
A：One UI 8 收紧了文件权限管理。先检查应用是否有权限读取目标路径，然后确认 `.env` 文件是否被正确打包进应用。可以用 adb shell run-as 查看应用私有目录下的实际文件。

Q3：react-native-config 和 dotenv 有什么区别？
A：react-native-config 是构建时解析，把变量注入 BuildConfig；dotenv 是运行时解析，把变量注入 process.env。前者在 Android 上更常用，后者在 Node.js 生态更常见。两者对大小写都是敏感的。

Q4：有没有办法让环境变量读取不区分大小写？
A：没有现成的库支持不区分大小写读取环境变量。但你可以自己写一个映射层，把 Config.API_KEY、Config.api_key、Config.ApiKey 都尝试一遍，取第一个非空值。

Q5：三星 S25 上 `.env` 文件应该放在哪个目录？
A：推荐放在项目根目录，由构建工具自动打包。如果需要在运行时动态读取，可以放在应用私有目录 /data/data/com.your.package.name/files/ 下，但要注意 One UI 8 的权限收紧问题。

总结

三星 S25 系列上 `.env` 配置失效，核心原因就是变量名大小写不一致导致的静默失败。这个问题在三星设备上更容易触发，主要和 One UI 文件系统兼容处理、Knox 安全框架、以及 One UI 8 的权限收紧有关。

排查思路很简单：先确认 `.env` 文件实际内容，再确认代码引用的大小写，最后用 debug: true 或 adb 命令验证加载结果。修复方案也不复杂：统一全大写命名，或者加一层映射兜底。

老实讲，这个坑排查起来确实费时间，但一旦理解了机制，后面就再也不会被它绊住了。希望这篇文章能帮你省下那几个小时的排查时间。如果你在三星 S25 上还遇到过其他 `.env` 相关的诡异问题，欢迎在评论区交流，大家一起避坑。