environment

环境配置

使用 CLI 读取和编辑 Railway 环境配置。

前置条件

需要 Railway CLI v4.27.3+。使用以下命令检查：

railway --version

如果版本低于 4.27.3，请升级：

railway upgrade

快速操作

当用户询问“配置是什么”或“显示配置”时：

railway environment config --json

展示：来源（仓库/镜像）、构建设置、部署设置、各服务的变量。

当用户询问“有哪些变量”或“显示环境变量”时：

使用相同的命令——railway environment config --json 包含各服务的变量和共享变量。

要查看渲染后（已解析）的变量值：railway variables --json

适用场景

• 用户想创建新环境
• 用户想复制环境（例如，“将生产环境复制到预发布环境”）
• 用户想切换到其他环境
• 用户询问当前的构建/部署设置、变量、副本数、运行状况检查、域名
• 用户询问如何更改服务来源（Docker 镜像、分支、提交、根目录）
• 用户想将服务连接到 GitHub 仓库
• 用户想从 GitHub 仓库部署（先通过 new 技能创建空服务，然后使用此功能）
• 用户询问如何更改构建或启动命令
• 用户想添加/更新/删除环境变量
• 用户想更改副本数或配置运行状况检查
• 用户询问如何删除服务、卷或存储桶
• 自动修复从日志中检测到的构建错误

创建环境

在已关联的项目中创建新环境：

railway environment new <name>

复制现有环境：

railway environment new staging --duplicate production

指定服务专属变量：

railway environment new staging --duplicate production --service-variable api PORT=3001

切换环境

将其他环境关联到当前目录：

railway environment <name>

也可以使用 ID：

railway environment <environment-id>

获取上下文

JSON 输出——项目/环境 ID 和服务列表：

railway status --json

提取：

• project.id — 项目 ID
• environment.id — 环境 ID

纯文本输出——已关联的服务名称：

railway status

显示 Service: <name> 行，其中包含当前已关联的服务。

解析服务 ID

从环境配置中获取服务 ID：

railway environment config --json | jq '.services | keys'

通过状态将服务 ID 映射到名称：

railway status --json

project.services 数组包含每个服务的 { id, name }。将其与 environment config 中的服务键匹配。

读取配置

获取当前环境配置：

railway environment config --json

响应结构

{
  "services": {
    "<serviceId>": {
      "source": { "repo": "...", "branch": "main" },
      "build": { "buildCommand": "npm run build", "builder": "NIXPACKS" },
      "deploy": {
        "startCommand": "npm start",
        "multiRegionConfig": { "us-west2": { "numReplicas": 1 } }
      },
      "variables": { "NODE_ENV": { "value": "production" } },
      "networking": { "serviceDomains": {}, "customDomains": {} }
    }
  },
  "sharedVariables": { "DATABASE_URL": { "value": "..." } }
}

完整字段参考请参阅 reference/environment-config.md。

变量语法和服务连接模式请参阅 reference/variables.md。

获取渲染后的变量

environment config 返回的是未渲染的变量——会保留 ${{shared.DOMAIN}} 等模板语法。这适用于管理和编辑。

要查看运行时显示的渲染后（已解析）值：

# Current linked service
railway variables --json

# Specific service
railway variables --service <service-name> --json

适用场景：

• 调试连接问题（查看实际 URL/端口）
• 验证变量解析是否正确
• 查看 Railway 注入的值（RAILWAY_*）

编辑配置

向 railway environment edit 传递 JSON 补丁以应用更改。补丁会与现有配置合并并立即提交，从而触发部署。

railway environment edit --json <<< '<json-patch>'

附带提交消息：

railway environment edit -m "description of change" --json <<< '<json-patch>'

示例

设置构建命令：

railway environment edit --json <<< '{"services":{"SERVICE_ID":{"build":{"buildCommand":"npm run build"}}}}'

添加变量：

railway environment edit -m "add API_KEY" --json <<< '{"services":{"SERVICE_ID":{"variables":{"API_KEY":{"value":"secret"}}}}}'

删除变量：

railway environment edit --json <<< '{"services":{"SERVICE_ID":{"variables":{"OLD_VAR":null}}}}'

删除服务：

railway environment edit --json <<< '{"services":{"SERVICE_ID":{"isDeleted":true}}}'

设置副本数：

railway environment edit --json <<< '{"services":{"SERVICE_ID":{"deploy":{"multiRegionConfig":{"us-west2":{"numReplicas":3}}}}}}'

添加共享变量：

railway environment edit --json <<< '{"sharedVariables":{"DATABASE_URL":{"value":"postgres://..."}}}'

批量应用多项更改

在单个补丁中包含多个字段，以原子方式应用更改：

railway environment edit -m "configure build, start, and env" --json <<< '{"services":{"SERVICE_ID":{"build":{"buildCommand":"npm run build"},"deploy":{"startCommand":"npm start"},"variables":{"NODE_ENV":{"value":"production"}}}}}'

错误处理

找不到命令

如果无法识别 railway environment edit，请升级 CLI：

railway upgrade

找不到服务

Service "foo" not found in project. Available services: api, web, worker

配置无效

常见问题：

• buildCommand 和 startCommand 不能相同
• buildCommand 仅适用于 NIXPACKS 构建器
• dockerfilePath 仅适用于 DOCKERFILE 构建器

没有权限

You don't have permission to modify this environment. Check your Railway role.

未关联项目

No project linked. Run `railway link` to link a project.

Composability

• Create service: Use service skill
• View logs: Use deployment skill
• Add domains: Use domain skill
• Deploy local code: Use deploy skill