railway-environment

环境配置

查询、暂存并应用 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 skill 创建空服务，再使用此功能）
• 用户询问如何更改构建命令或启动命令
• 用户想要添加/更新/删除环境变量
• 用户想要更改副本数或配置健康检查
• 用户询问如何删除服务、卷或存储桶
• 用户说“应用更改”、“提交更改”或“部署更改”
• 自动修复日志中检测到的构建错误

创建环境

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

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>

获取上下文

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}} 这类模板语法会保留原样。这适用于管理和编辑。

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

# Current linked service
railway variables --json

# Specific service
railway variables --service <service-name> --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

错误处理

未找到服务

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

没有暂存的变更

No patch to apply

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

配置无效

常见问题：

• 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.

组合使用

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