name: railway-environment description: 查询、暂存和应用Railway环境的配置变更。用于任何变量或环境变量操作、服务配置（源、构建设置、部署设置）、生命周期（删除服务）以及应用变更。对于任何配置或变量查询，优先于此技能而非railway-status技能。 version: 1.0.0 author: Railway license: MIT tags: [Railway, 环境, 配置, 变量, 构建, 部署, 基础设施, 设置] dependencies: [railway-cli] allowed-tools: Bash(railway:*)

环境配置

查询、暂存和应用Railway环境的配置变更。

Shell转义

关键： 当通过bash运行GraphQL查询时，必须使用heredoc包装以防止shell转义问题：

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh 'query ...' '{"var": "value"}'
SCRIPT

没有heredoc包装，多行命令会中断，GraphQL非空类型中的感叹号会被转义，导致查询失败。

何时使用

用户想要创建新环境
用户想要复制环境（例如，“复制生产环境到暂存环境”）
用户想要切换到不同环境
用户询问当前构建/部署设置、变量、副本、健康检查、域名
用户请求更改服务源（Docker镜像、分支、提交、根目录）
用户想要将服务连接到GitHub仓库
用户想要从GitHub仓库部署（首先通过railway-new技能创建空服务，然后使用此技能）
用户请求更改构建或启动命令
用户想要添加/更新/删除环境变量
用户想要更改副本数量或配置健康检查
用户请求删除服务、卷或存储桶
用户说“应用变更”、“提交变更”、“部署变更”
自动修复在日志中检测到的构建错误

创建环境

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

railway environment new <名称>

复制现有环境：

railway environment new staging --duplicate production

带服务特定变量：

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

切换环境

将不同环境链接到当前目录：

railway environment <名称>

或通过ID：

railway environment <环境ID>

获取上下文

railway status --json

提取：

project.id - 用于服务查找
environment.id - 用于突变
service.id - 默认服务（如果用户未指定）

解析服务ID

如果用户通过名称指定服务，查询项目服务：

query projectServices($projectId: String!) {
  project(id: $projectId) {
    services {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

匹配服务名称（不区分大小写）以获取服务ID。

查询配置

获取当前环境配置和暂存变更。

query environmentConfig($environmentId: String!) {
  environment(id: $environmentId) {
    id
    config(decryptVariables: false)
    serviceInstances {
      edges {
        node {
          id
          serviceId
        }
      }
    }
  }
  environmentStagedChanges(environmentId: $environmentId) {
    id
    patch(decryptVariables: false)
  }
}

示例：

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'query envConfig($envId: String!) {
    environment(id: $envId) { id config(decryptVariables: false) }
    environmentStagedChanges(environmentId: $envId) { id patch(decryptVariables: false) }
  }' \
  '{"envId": "ENV_ID"}'
SCRIPT

响应结构

config 字段包含当前配置：

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

environmentStagedChanges 中的 patch 字段包含待定变更。有效配置是基础 config 与暂存 patch 合并的结果。

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

有关变量语法和服务布线模式，请参阅 reference/variables.md。

获取渲染变量

上面的GraphQL查询返回未渲染变量 - 模板语法如 ${{shared.DOMAIN}} 被保留。这对于管理/编辑是正确的。

要查看渲染（解析）值（如运行时出现）：

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

# 特定服务
railway variables --service <服务名称> --json

何时使用：

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

暂存变更

通过 environmentStageChanges 突变暂存配置变更。使用 merge: true 自动与现有暂存变更合并。

mutation stageEnvironmentChanges(
  $environmentId: String!
  $input: EnvironmentConfig!
  $merge: Boolean
) {
  environmentStageChanges(
    environmentId: $environmentId
    input: $input
    merge: $merge
  ) {
    id
  }
}

重要： 始终使用变量（非内联输入），因为服务ID是UUID，不能用作未引用的GraphQL对象键。

示例：

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!, $merge: Boolean) {
    environmentStageChanges(environmentId: $environmentId, input: $input, merge: $merge) { id }
  }' \
  '{"environmentId": "ENV_ID", "input": {"services": {"SERVICE_ID": {"build": {"buildCommand": "npm run build"}}}}, "merge": true}'
SCRIPT

删除服务

使用 isDeleted: true：

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!, $merge: Boolean) {
    environmentStageChanges(environmentId: $environmentId, input: $input, merge: $merge) { id }
  }' \
  '{"environmentId": "ENV_ID", "input": {"services": {"SERVICE_ID": {"isDeleted": true}}}, "merge": true}'
SCRIPT

暂存并立即应用

对于应立即使部署的单次变更，使用 environmentPatchCommit 在一次调用中暂存和应用。

mutation environmentPatchCommit(
  $environmentId: String!
  $patch: EnvironmentConfig
  $commitMessage: String
) {
  environmentPatchCommit(
    environmentId: $environmentId
    patch: $patch
    commitMessage: $commitMessage
  )
}

示例：

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation patchCommit($environmentId: String!, $patch: EnvironmentConfig, $commitMessage: String) {
    environmentPatchCommit(environmentId: $environmentId, patch: $patch, commitMessage: $commitMessage)
  }' \
  '{"environmentId": "ENV_ID", "patch": {"services": {"SERVICE_ID": {"variables": {"API_KEY": {"value": "secret"}}}}}, "commitMessage": "add API_KEY"}'
SCRIPT

何时使用： 单次变更，无需批处理，用户希望立即部署。

何时不使用： 需要批处理的多个相关变更，或用户说“仅暂存”/“先不部署”。

应用暂存变更

提交暂存变更并触发部署。

注意： 没有 railway apply CLI命令。使用以下突变或直接引导用户到Web UI。

应用突变

突变名称：environmentPatchCommitStaged

mutation environmentPatchCommitStaged(
  $environmentId: String!
  $message: String
  $skipDeploys: Boolean
) {
  environmentPatchCommitStaged(
    environmentId: $environmentId
    commitMessage: $message
    skipDeploys: $skipDeploys
  )
}

示例：

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation commitStaged($environmentId: String!, $message: String) {
    environmentPatchCommitStaged(environmentId: $environmentId, commitMessage: $message)
  }' \
  '{"environmentId": "ENV_ID", "message": "add API_KEY variable"}'
SCRIPT

参数

字段	类型	默认值	描述
`environmentId`	String!	-	来自状态的环境ID
`message`	String	null	变更的简短描述
`skipDeploys`	Boolean	false	跳过部署（仅当用户明确要求时）

提交消息

保持非常简短 - 最多一句话。示例：

“设置构建命令以修复npm错误”
“添加API_KEY变量”
“将副本增加到3”

如果没有有意义的描述，留空。

默认行为

除非用户明确要求跳过，否则始终部署。 仅当用户说“应用但不部署”、“提交但不部署”或“跳过部署”时，才设置 skipDeploys: true。

成功时返回工作流ID（字符串）。

自动应用行为

默认情况下，立即应用变更。

流程

单次变更： 使用 environmentPatchCommit 在一次调用中暂存和应用。

多次变更或批处理： 对每次变更使用 environmentStageChanges 和 merge: true，然后使用 environmentPatchCommitStaged 应用。

何时不自动应用

用户明确说“仅暂存”、“先不部署”或类似
用户正在进行应一起部署的多个相关变更

当您不自动应用时，告诉用户：

变更已暂存。在以下位置应用：https://railway.com/project/{projectId} 或请求我应用它们。

从 railway status --json → project.id 获取 projectId

错误处理

服务未找到

项目中的服务“foo”未找到。可用服务：api, web, worker

无暂存变更

无补丁可应用

没有暂存变更可提交。先暂存变更。

无效配置

常见问题：

buildCommand 和 startCommand 不能相同
buildCommand 仅对NIXPACKS构建器有效
dockerfilePath 仅对DOCKERFILE构建器有效

无权限

您无权修改此环境。检查您的Railway角色。

无链接项目

无项目链接。运行 `railway link` 以链接项目。

可组合性

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