---
title: "环境变量"
description: "Kiln 支持的全部环境变量，以及各变量的取值、作用和配置优先级。"
---

> Documentation Index
> Fetch the complete documentation index at: https://kiln.wbxdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 环境变量

Kiln 在启动时读取环境变量，运行期间不再重读。除非特别说明，只有非空值才会生效，留空等同未设置。

## 服务端变量

| 变量 | 作用 | 取值 | 优先级 |
| --- | --- | --- | --- |
| `KILN_LISTEN` | 覆盖 `server.listen` | `host:port` 形式 | 高于配置文件 |
| `KILN_PUBLIC_BASE_URL` | 覆盖 `server.public_base_url` | 绝对 URL，尾部斜杠会被去掉 | 高于配置文件 |
| `KILN_DATA_DIR` | 覆盖 `server.data_dir` | 目录路径 | 高于配置文件 |
| `KILN_TOKEN_PRIVATE_KEY` | 覆盖 `auth.token_private_key` | Ed25519 私钥 PEM 内容 | 高于配置文件 |
| `KILN_TOKEN_PRIVATE_KEY_FILE` | 覆盖 `auth.token_private_key_file` | 文件路径 | 高于配置文件 |
| `KILN_TOKEN_PUBLIC_KEY` | 覆盖 `auth.token_public_key` | Ed25519 公钥 PEM 内容 | 高于配置文件 |
| `KILN_TOKEN_PUBLIC_KEY_FILE` | 覆盖 `auth.token_public_key_file` | 文件路径 | 高于配置文件 |
| `KILN_RESOURCE_MODE` | 覆盖 `server.resource_mode` | `auto`、`performance`、`constrained` | 高于配置文件 |
| `KILN_RESOURCE_MEMORY_MB` | 覆盖内存探测结果 | 正整数，单位 MiB | 高于自动探测 |
| `KILN_RESOURCE_CPUS` | 覆盖 CPU 探测结果 | 正整数核数 | 高于自动探测 |
| `KILN_RUNTIME_VARIANT` | 标记运行时变体 | `core`、`full`，留空即 `standalone` | 无对应配置键 |
| `KILN_LOG_LEVEL` | 覆盖 `logging.level` | `debug`、`info`、`warn`、`error` | 高于配置文件 |
| `KILN_LOG_FORMAT` | 覆盖 `logging.format` | `text`、`json` | 高于配置文件 |
| `KILN_LOG_COLOR` | 覆盖 `logging.color` | `auto`、`always`、`never` | 高于配置文件 |
| `KILN_DEFAULT_PACKAGER_ENGINE` | 提供 `packager.engine` 的兜底值 | `auto`、`native`、`ffmpeg` | 低于配置文件 |
| `KILN_PLAY_OPEN` | 控制 `security.play_require_auth` | `1`、`true`、`TRUE` 关闭鉴权；`0`、`false`、`FALSE` 要求鉴权 | 决定权在环境变量 |
| `GOMEMLIMIT` | Go 运行时软内存上限 | Go 运行时接受的大小写法，如 `128MiB` | 始终最优先 |
| `GOGC` | Go 垃圾回收目标百分比 | Go 运行时接受的值，如 `100` 或 `off` | 阻止资源自适应改写 GC 目标 |
| `NO_COLOR` | 关闭日志着色 | 任意非空值 | 仅影响 `auto` 着色 |

## 优先级规则

多数变量在配置解析之后、填充默认值之前应用，因此顺序是**环境变量 高于 配置文件 高于 内置默认值**。以下几项不遵循这个通用顺序。

### KILN_DEFAULT_PACKAGER_ENGINE 只在配置未填时生效

它是在填充默认值阶段读取的，且仅当 `packager.engine` 为空时才被采用；配置里写了任何值，环境变量都不生效。采用之后仍要通过统一校验，取值不在 `auto`、`native`、`ffmpeg` 之内会导致启动失败。Lite 变体在加载配置之前会把未设置的该变量置为 `native`，并且拒绝任何非 `native` 的引擎。

### KILN_PLAY_OPEN 覆盖配置里的播放鉴权

环境变量取 `1`、`true`、`TRUE` 时把 `security.play_require_auth` 置为 `false`，取 `0`、`false`、`FALSE` 时置为 `true`，其余取值不做覆盖。变量未设置时以配置文件为准：`play_require_auth` 是可选布尔，不写默认要求鉴权，显式写 `false` 即可关闭。无论走哪条路径，关闭播放鉴权都只适合调试环境。

### GOMEMLIMIT 始终压过配置与自动计划

Kiln 只在 `server.memory_limit_mb` 为正数且 `GOMEMLIMIT` 未设置时，才主动为 Go 运行时设置软内存上限。只要 `GOMEMLIMIT` 存在，运行时就以它为准，配置值与资源自适应算出的档位预算都不再改写这项设置。

### GOGC 覆盖资源档位的回收目标

未设置 `GOGC` 时，Kiln 会按资源档位调整 Go 的垃圾回收目标。只要该变量存在，Kiln 就不会再写入档位值，具体行为由 Go 运行时解释。

### KILN_RESOURCE_MEMORY_MB 与 KILN_RESOURCE_CPUS 改的是探测值

这两个变量不覆盖任何配置键，而是替换掉资源探测的结果，再由资源自适应据此计算档位。只接受正整数，无法解析、非正数或超出范围的值会被忽略并沿用探测结果。它们适合用在探测不准的宿主机上，或者用来复现某一个档位。`server.resource_mode = "performance"` 会让自适应整体退出，此时改这两个变量没有意义。

### NO_COLOR 只在 auto 模式下起作用

着色策略先看 `logging.color` 或 `KILN_LOG_COLOR`：取 `always` 时强制着色，此时不再检查 `NO_COLOR`；取 `never` 时关闭着色；取 `auto`（默认）时，只有输出是终端设备且 `NO_COLOR` 未设置才着色。JSON 格式的日志不着色。

### KILN_RUNTIME_VARIANT 只影响自我标识

留空视为 `standalone`，`core` 与 `full` 是有效值，其它值会在启动日志里打印一条警告并按 `standalone` 处理。官方容器镜像已经内置了对应取值，通常不需要手动设置。各变体的能力差异见 [发行变体](/guide/variants/)。

## 安装脚本变量

安装脚本读取的是另一组变量，只在安装与升级过程中起作用，与服务端运行时无关。

| 变量 | 作用 |
| --- | --- |
| `KILN_YES` | 置为 `1` 时跳过全部交互确认 |
| `KILN_VERSION` | 指定要安装的版本 |
| `KILN_VARIANT` | 选择 `full` 或 `lite`，其它值报错退出 |
| `KILN_INSTALL_DIR` | 指定安装目录 |
| `KILN_MIRROR` | 指定下载镜像 |
| `KILN_NO_MIRROR` | 置为 `1` 时禁用镜像 |
| `KILN_LANG` | 强制脚本输出语言 |
| `KILN_DRY_RUN` | 置为 `1` 时只演示流程，不实际写入 |

安装脚本同样遵守 `NO_COLOR`。用法详见 [安装脚本](/start/install-script/)。

> **仅供开发的变量**
>
> 仓库里还有一批只服务于压测工具、镜像冒烟脚本与测试的变量，它们不影响正式部署，也不在本页范围内。

Source: https://kiln.wbxdocs.com/reference/env/index.mdx