Support structured env config reload

[yiguodev]

修改内容

新增配置根 env，使用结构化 EnvConfig 配置可运行时重载的 Xray 环境项，并在配置构建时应用。

xray run --env 已移除；xray.json.strict、xray.location.config、xray.location.confdir 继续通过进程环境变量提供。

验证

• go test ./main ./common/platform ./infra/conf ./infra/conf/serial -count=1

AI 辅助：GPT-5.5 Extra High

[Copilot]

Pull request overview

This PR adds a repeatable --env KEY=VALUE flag to xray run, applying environment variables before config load and before -test / -dump / normal startup, improving reliability in launch scenarios where environment inheritance is unreliable (e.g., Windows elevation).

Changes:

• Add a repeatable -env/--env flag (backed by cmdarg.Arg) and apply the provided KEY=VALUE pairs via os.Setenv at the start of executeRun.
• Add applyRunEnvVars helper to parse and validate KEY=VALUE inputs.
• Add unit tests covering valid and invalid --env values.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
main/run.go	Adds --env flag wiring, applies env vars before config-related actions, and documents the new flag.
main/run_env_test.go	Adds tests for applyRunEnvVars behavior (success cases and invalid input rejection).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[RPRX]

之前我想给配置文件加个 env 结构但有些地方读 env 是在 init() 里的就搁置了，你这个 PR 没问题吗

[yiguodev]

AI 梳理了一下，确实不行。目前仅支持以下 env 可用。

xray.location.config
xray.location.confdir
xray.location.asset
xray.location.cert
xray.cone.disabled
xray.tun.fd

后续可以单独开 PR 优化一下。

[RPRX]

说实话这个 PR 可能不会合，你都命令行启动了，命令行本来就能设临时环境变量

[yiguodev]

你说的对。
不过这个 PR 核心就解决一个场景，就是 Windows 上 UAC 提权启动的时候，是没有可靠手段来设置或者传递环境变量的。
大概位置在 https://github.com/OneXray/OneXray/blob/ae9e3f61ddb7033fdaa8648794d6833b6d19be04/lib/core/ffi/windows_ffi_api.dart#L50

[RPRX]

Windows 上设临时环境变量需要多行，你就不能弄个特权命令行再启动 Xray 吗

[RPRX]

总之你要真想加这种东西就加个 env 根配置，用的人还更多一些，然后有些 init() 的看看能不能改成延时读取啥的

[yiguodev]

OK。我再研究研究。

[yiguodev]

目前有三个 env 设置没法放到配置里。

xray.json.strict
xray.location.config
xray.location.confdir

计划分成两部分，--env 可以设置这三个 key，其他 key 统一由配置文件更新。

[RPRX]

读配置文件之前的 env 那确实没办法，但还是我说的，命令行本来就能设临时环境变量，感觉没必要徒增复杂度

[RPRX]

就是说有一种多打包进了一个 wxray.exe 的那种感觉

[yiguodev]

其实做这个修改主要想在 Windows 和 Linux 上直接用官方裸核，原来 libXray 是有一层 wrapper 的。

[yiguodev]

算了，PR 先关了。我再想想用哪种方式更好一些。

[RPRX]

PR 不用关，改成配置文件里写 env 就行

我的意思是通过命令行加临时环境变量本来就不用改 Xray 的代码，你研究一下

[yiguodev]

1. 除 xray.tun.fd 外，单元测试已覆盖所有 key 。
2. xray.tun.fd，xray.location.asset 已经通过所有平台的实机测试。

[yiguodev]

已同步添加文档。

XTLS/Xray-docs-next#874

[Meo597]

新开配置块的话要不要给默认配置文件标个编号 docker install doc 里目前是都有

[yiguodev]

已补充 12_env.json

[RPRX]

文档把 env 移到“基础配置”吧，这个的确更应该跟配置项们放一起

[yiguodev]

文档已调整

[RPRX]

没看你那个 test 是咋写的但如果只是读取、验证的话盲猜没用，因为你这个读取、验证不是在 init() 里

写 test 用处不大，要把 init() 里的都改成延时读取才行

[Fangliding]

只是AI干什么都喜欢写个test而已

[yiguodev]

没看你那个 test 是咋写的但如果只是读取、验证的话盲猜没用，因为你这个读取、验证不是在 init() 里

写 test 用处不大，要把 init() 里的都改成延时读取才行

现在 init 里已经不读取环境变量了。

[yiguodev]

核心的修改思路是保留原有的包内变量，但改为实时读取，并加入 reload 机制。

[RPRX]

env 全放一个地方统一读取，本来在 init 里要初始化变量啥的改为在启动 Xray Instance 之前统一回调，这个思路没啥问题

不过把 test 全删了吧，感觉没必要

[yiguodev]

已处理：删除了这次新增的 env reload / root env 相关测试，只保留实现逻辑。

本地验证：

• git diff --check
• go test ./common/platform ./infra/conf/serial ./infra/conf ./core ./main -count=1

其中 infra/conf 本地测试需要 resources/geoip.dat / resources/geosite.dat，我使用本地已有 geodata 临时链接后验证通过，测试后已清理。

[RPRX]

调用 ReloadEnvSettings() 的地方似乎有几处没必要？似乎只保留启动 Xray Instance 之前那处就行了

[RPRX]

不对，还有 geo 的 env，所以配置加载前要有，配置加载由于涵盖 env，所以之后也要有

[RPRX]

所以 Xray run 那个 ReloadEnvSettings() 是否有必要

[yiguodev]

已调整：ReloadEnvSettings() 现在只在创建 Xray instance 前调用一次。

具体改动：

• 删除 main/run.go 的启动入口 reload；
• 删除 core.LoadConfig() 的 reload；
• 删除 core.New() / core.NewWithContext() 各自重复的 reload；
• 在它们共同进入的 initInstanceWithConfig() 开头统一 reload；
• ApplyConfigEnvSettings() 现在只负责写入配置根 env 到进程环境，不再立即 reload；rollback 也只恢复环境变量。

这样配置根 env 仍会在 instance 初始化前统一生效，调用点也只保留一处。

[RPRX]

别啥都丢给 AI 啊，我是让你思考，比如说由于有 geo 的 env，配置加载前也要有

[yiguodev]

重新梳理和优化了一下，逻辑上没问题了。

xray.location.config
xray.location.confdir
xray.json.strict

这三个本身配置内 env 是不支持的，也不受 reload 的影响。

xray.location.asset
xray.location.cert

这两个会在 Config.Build() 内使用， 但是直接读取 env ，不依赖 reload。读取前 env 已经生效。

其余的

xray.buf.readv
xray.buf.splice
xray.vmess.padding
xray.cone.disabled
xray.ray.buffer.size
xray.browser.dialer
xray.xudp.show
xray.xudp.basekey
xray.tun.fd

均在 initInstanceWithConfig 之后读取。

[RPRX]

@yiguodev 把配置解析 env 的优先级提到最前面就可以在配置中写那两个 env 了

[yiguodev]

目前的执行顺序是对的。

https://github.com/XTLS/Xray-core/pull/6400/changes#diff-2683dbaba14bc856bb5c6f6e664313d25dd246b4e262deb3e886579b4f48a3b4R570

ApplyConfigEnvSettings 在第一行。

xray.location.asset
xray.location.cert

读到的就是 config 里配置的 env value 。

[RPRX]

感觉配置解析的代码有点啰嗦了，不能简化为 for 加上 os.SetEnv 吗，不要一个个都写出来，另外需要支持 _ 的格式

这样的话由于 ReloadEnvSettings() 主要是回调调用，只放启动 instance 前那一处似乎没问题，因为那两个 env 不需要回调

[RPRX]

env_reload.go 里似乎也不需要把所有 env 都列出来，都走 os 包来存取就行，这个文件似乎也能大幅简化代码

[yiguodev]

感觉配置解析的代码有点啰嗦了，不能简化为 for 加上 os.SetEnv 吗，不要一个个都写出来，另外需要支持 _ 的格式

这样的话由于 ReloadEnvSettings() 主要是回调调用，只放启动 instance 前那一处似乎没问题，因为那两个 env 不需要回调

这块是有意设计，本意是限制开发者不要随意设置 env ，只暴露支持的 env key。
我再简化一下。

[RPRX]

但是以后若加个 env 要改很多处就很难绷，按现在的写法加个 env 要改至少四个文件

[yiguodev]

重新简化了一版。支持的 key 已进行运行时验证，读取正常。