每一项设置都是一个环境变量
每一项设置都是环境变量——外加一个用于路径拒绝规则的可选文件 .oxphpdeny——而每个变量都有一个能在生产环境中站得住脚的默认值。先部署一个空环境，然后只覆盖你真正关心的变量。
超出这个集合的任何值——比如「ture」这类拼写错误——都会在启动时立即失败，并指出是哪个变量。空值等同于未设置：FOO=${FOO} 替换后得到 FOO= 时，会回退到默认值，而不是拒绝启动。
服务器与工作进程
15 个变量主 HTTP 服务器的地址和端口。
用于提供文件和 PHP 脚本的根目录。
单一规范入口脚本。未设置 = 直接文件映射，*.php = 前端控制器，非 .php = SPA 回退；在工作进程模式下即工作进程引导脚本。相对于 DOCUMENT_ROOT 解析。
启用常驻工作进程模式。要求 ENTRY_FILE 指向一个 .php 脚本。
最大并发 TCP 连接数。也是默认 QUEUE_MAX_WAITING 的上限来源（取其一半）；格式错误的值是启动错误。请让它保持高于 PHP_WORKERS + QUEUE_CAPACITY + QUEUE_MAX_WAITING。
异步 I/O 线程数。1 = 单线程，N = 固定数量，未设置 = 自动。与 PHP_WORKERS 共享 CPU 核心——把它调到全部核心数通常会降低吞吐量。CPU 指进程可以运行的核心数（亲和性掩码，并按 cgroup 配额下调），而不是 CPU 权重，也不是平台在容器外部施加的限制；启动日志行 CPU count for default sizing 会显示实际计入的数量。
PHP 执行器后端：sapi 使用真实 PHP，stub 用于不依赖 PHP 的基准测试。
工作进程池大小。N = 固定池，MIN:MAX = 动态伸缩，0 = 自动。自动确定大小时计算 CPU 的方式与 TOKIO_WORKERS 相同——在容器看不到其 CPU 限制的套餐上（启动日志中为 cpu_source: host），请显式设置这两个变量。
动态工作进程在被回收前保持空闲的秒数。回收会等到一个没有任何在途请求的时刻，因此在途请求绝不会被中途切断。
PHP 队列中最大待处理请求数；到达已满队列的请求最多等待 QUEUE_WAIT_TIMEOUT_MS。0 = 自动。对于 MIN:MAX 池，初始工作进程数等于最小值。
请求在得到 529 之前等待 PHP 工作进程的时长上限——一个截止时间同时覆盖等队列空位和在队列中等待。过载时服务器会自行缩短它（最低到 1/64，不少于 10 ms）；当前生效值见 oxphp_admission_wait_budget_us。0 = 队列一满就立即拒绝。
同时停放着等待队列空位的最大请求数；超过之后立即返回 529。每个等待者都占着一条连接和已缓冲的请求体。0 = 自动。
等待集合最多可持有的请求体字节数；会超出它的请求体立即得到 529，无请求体的请求照常等待。0 = 自动。
每个工作进程在被回收前的内存上限（MiB）。0 = 无限制。连续三个请求中途出错后工作进程也会被回收，或通过 Worker::scheduleExit() 按需回收。
在每个脚本运行前构建 $_SERVER 和 $_GET。假值 = 跳过这项工作；$_POST、$_FILES、$_COOKIE 和 php://input 不受影响。
流量与传输
18 个变量连接建立后接收 HTTP 请求头的最长秒数（Slowloris 防护）。
优雅关闭期间等待处理中请求完成的最长秒数；超时后剩余请求会被取消。卡在阻塞调用中的请求可能让进程拖过这一时限。
每个 IP 在每个时间窗口内的最大请求数。0 = 关闭；PHP 队列满时返回 529。
限流时间窗口的时长（秒）。
PEM 证书的路径。必须同时设置 TLS_CERT 和 TLS_KEY 才能启用 TLS。
PEM 私钥的路径。
最低 TLS 版本：1.2 或 1.3。即使 TLS 已关闭，也会在启动时校验。
每个连接同时打开的最大流数量。
连接被关闭前排队的最大 RST_STREAM 帧数（Rapid Reset 防护）。
每个请求解码后请求头的最大总字节数。
PING 帧之间的间隔秒数；0 表示禁用。
关闭连接前等待 PING 响应的秒数。
静态文件的 Cache-Control: max-age。接受 30s、5m、2h、30d、1w、1y、纯秒数或 off。替代 STATIC_CACHE_TTL。
内存缓存的 mtime 重新校验——每个文件最多每 3 秒检查一次。替代 STATIC_CACHE。
提供的内容编码：br、zstd、gzip。off/none 表示禁用压缩。顺序会被忽略——缓存的静态文件优先使用 Brotli，其余一律优先 zstd。
Brotli 压缩质量 0–11；0 表示撤下 Brotli。替代 COMPRESSION_LEVEL（它的 0 仍会禁用所有编码）。
Zstandard 压缩级别 0–19；0 表示撤下 zstd。超出范围的值会中止启动。
Gzip 压缩级别 0–9；0 表示撤下 gzip。超出范围的值会中止启动。
安全
5 个变量点击劫持防护：SAMEORIGIN、DENY 或 off。在每个响应上设置 X-Frame-Options 和 CSP frame-ancestors；应用自行设置的响应头始终优先。无效值会回退到 SAMEORIGIN 并给出启动警告。
可信代理：以逗号分隔的列表，可混合 CIDR、裸 IP 以及关键字 private 和 cloudflare。真实客户端 IP 通过“最右侧的非可信项”从 Forwarded / X-Forwarded-* 中提取；使用 cloudflare 时，若请求经由 Cloudflare 边缘节点到达，则从 CF-Connecting-IP 中提取。
其下的 .php 文件永不通过直接 URI 执行的 glob 模式（/uploads/**）。在磁盘 I/O 之前匹配——不会泄露文件是否存在。
命中 PHP_DENY_PATHS 或 .oxphpdeny 拒绝规则时的响应：一个 400–599 的 HTTP 状态码，或 DOCUMENT_ROOT 内以 / 开头的 PHP 回退脚本。在工作进程模式下，.oxphpdeny 拒绝规则只接受状态码。
允许符号链接逃逸出 DOCUMENT_ROOT 的绝对路径。未设置 = 不允许任何逃逸。
日志、追踪与性能剖析
39 个变量服务器自身诊断日志的详细程度：trace、debug、info、warn、error。不过滤访问日志；客户端断开连接记录在 debug 级别。
按请求记录的访问日志：all = 每个请求，error = 仅 4xx/5xx，未设置 = 关闭。
内部服务器（/health、/metrics、/config）。仅指定端口时绑定到 127.0.0.1；未设置 = 不启动。
内部服务器的 CIDR 允许列表；列表外的来源返回 403，健康探测仍可访问。回环地址不会被隐式允许。
存放自定义 {status}.html 错误页面的目录。
内部查询端点的最大请求体字节数（512 KiB）。
W3C Trace Context 传播：读取 traceparent/tracestate 并通过 $_SERVER 转发给 PHP。
启用 OpenTelemetry span 导出。隐含 TRACE_CONTEXT=true。
导出协议：grpc 或 http/protobuf。
OTLP 采集器端点。使用 http/protobuf 时它是一个基础 URL：span 会发送到其下的 /v1/traces。
导出超时时间（毫秒）。使用 gRPC 时，它还约束连接采集器的过程（包括 TLS 握手），并在 Linux 上决定不再接收数据的连接会在多久之后被关闭。
认证请求头：key=value,key2=value2。
导出 span 中的服务名称。
服务版本属性。
额外的资源属性：env=prod,region=us-east-1。
采样策略：always_on、always_off、traceidratio 以及各 parentbased_* 变体。
基于比例的采样器的采样率 0.0–1.0；超出范围的值会被钳制。
APM：自动埋点 34 个 PHP 函数（PDO、mysqli、cURL、Redis……）、错误捕获、追踪 SDK。要求 OTEL_ENABLED。关闭时 oxphp_apm_trace() 仍会执行其回调。
慢查询阈值（毫秒）；更慢的数据库查询会被标记为 oxphp.db.slow=true。
在 db.params span 中记录绑定参数。按原样记录（不脱敏），因此可能把 PII 放进追踪数据——只在可以接受这一点的场合启用。
exception.stacktrace 属性的长度上限；从尾部截断。0 = 不截断。
exception.message 属性的长度上限（New Relic 的单属性限制）；从尾部截断。0 = 不截断。
总开关。其他 PROFILER_* 变量仍会被解析，因此拼写错误会在启动时暴露。
请求被采样的概率 0.0–1.0。
同时对内部服务器的请求进行采样。
显式触发方式（X-OxPHP-Profile 请求头、OXPROF cookie、__oxprof 查询参数）必须携带的密钥，也是 /__profiler/* 的 Bearer 令牌。未设置 = 不需要令牌。采样和 OxPHP\Profile\* 函数从不检查它。
每个请求的 span 上限；超出的剖析数据会被截断。
记录调用的最大嵌套深度；更深调用的耗时会并入处于该上限的那一层调用。被钳制为 32。
磁盘上剖析文件的存放目录。
写入磁盘的格式：xhprof、speedscope、pprof、flamegraph。
每秒写入剖析文件数量的限流。
保留的最大剖析文件数量；较旧的会被清理。
用于 POST 上传剖析数据的远程端点。
导出时使用的传输格式。
每次导出时发送的 Bearer 令牌。
XHGui 兼容的封装；未设置 = 根据 URL 自动检测。
Buggregator 信封（始终为 xhprof）；未设置 = 根据 URL 自动检测。与 PROFILER_EXPORT_XHGUI 互斥。
用于项目分组的 Buggregator app_name。
Buggregator 标签：key=value,key2=value2。格式错误的项是启动错误。
异步与共享状态
18 个变量按需启用：用挂起纤程的实现替换阻塞式内置函数。类别：sleep（原生 sleep/usleep）、streams（阻塞的 tcp:// 读取和 stream_select）、net（建立连接、TLS 握手与读取、等待缓冲区空间的写入、unix:// / udp:// / udg:// 读取——需要同时启用 streams，仅限 Linux）。1/true/all = 所有类别。已安装的集合显示在 /config 的 runtime_hooks 中。
专用的异步工作线程。0 = 函数已注册但调用时抛出 AsyncException。
异步队列中最大待处理任务数。0 = 自动。
每个工作线程并发任务纤程的上限；全局处理中上限 = 纤程数 × 工作线程数。
整个 OxPHP\Shared\* 子系统的总开关。关闭 = 其类完全不会注册；请用 class_exists() 做防护。
存活 Shared 对象的全局上限（Map 的键不计入）；超出后再创建会抛出 CapacityException。
Shared 对象估算内存的全局上限，仅在创建对象时检查。
开关 oxphp_shared_* 的 Prometheus 指标暴露。
开关 /__ox_shared/* 自省 API。
自省响应中的值预览；若预览可能泄露数据，请禁用。
环检测的 BFS 深度；对于较深的图可调高。
环检测期间遍历的边数；对于较稠密的图可调高。
单个值的大小上限；更大的插入会快速失败。
单个通道的总负载上限。
Shared\Mutex 的死锁检测器：off、warn（记录日志并计数环路）或 strict（抛出 DeadlockException 打破环路）。调试构建默认为 strict。
死锁检测器的扫描间隔（毫秒）。
预览中单个字符串的截断长度，以字节计，在字符边界处截断。
/entry 预览中采样的条目数。
配置示例
直接取自文档的起点——复制一份再按需调整。
内部服务器运行时，/config 会以 JSON 返回解析后的配置。TLS 路径、INTERNAL_ADDR 和 ERROR_PAGES_DIR 会从响应中剔除。
零配置也是一种有效配置
上面每一个默认值的选择，都是为了让空环境开箱即用。