environment

用途

本技能用于通过 Railway 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

创建环境

在已链接的项目中创建新环境：

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'

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

railway status --json

project.services 数组包含每个服务的 { id, name }，可与环境配置中的服务键匹配。

读取配置

获取当前环境配置：

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}} 会被保留，这适合管理/编辑。

查看运行时渲染（解析）后的值：

# 当前链接的服务
railway variables --json

# 指定服务
railway variables --service <service-name> --json

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

编辑配置

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

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://..."}}}'

批量修改：在单个 patch 中包含多个字段以原子方式应用：

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"}}}}}'

适用场景

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

错误处理

命令未找到：若 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.

组合使用

创建服务：使用 service 技能
查看日志：使用 deployment 技能
添加域名：使用 domain 技能
部署本地代码：使用 deploy 技能

限制

资料未提供除上述 CLI 版本要求、权限与配置校验之外的更多限制说明。