用途:管理 Railway 项目的环境配置,包括查询当前配置与暂存变更、创建或复制环境、切换环境,以及修改服务来源(Docker 镜像、分支、提交、根目录)、构建与启动命令、环境变量、副本数、健康检查、域名,删除服务/卷/存储桶,并提交部署。
主要能力:通过 railway status --json 获取 project.id、environment.id、service.id;用 GraphQL 查询 environment.config 与 environmentStagedChanges 获取基础配置和待应用补丁;用 environmentStageChanges(merge: true)暂存变更;用 environmentPatchCommit 单次暂存并立即应用;用 environmentPatchCommitStaged 提交已暂存变更并触发部署。变量查询用 railway variables --json 查看渲染后的运行时值。
使用方式:创建环境 railway environment new <name>,复制 railway environment new staging --duplicate production,切换 railway environment <name>。GraphQL 调用必须用 heredoc 包裹,例如 bash <<'SCRIPT' 后接 ${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh 'query ...' '{"var": "value"}',否则多行命令与感叹号会被 shell 转义导致失败。暂存变更时始终使用变量传参,因为服务 ID 是 UUID,不能作为未加引号的 GraphQL 对象键。
适用场景:需要批量修改环境配置、复制生产到预发、调整构建/启动命令、增删环境变量、修改副本或健康检查、连接 GitHub 仓库、删除资源,以及根据日志自动修复构建错误。
限制:没有 railway apply CLI 命令,应用暂存变更需用 environmentPatchCommitStaged 或网页 UI;默认会部署,仅当用户明确要求跳过时才设 skipDeploys: true;buildCommand 与 startCommand 不能相同,buildCommand 仅适用于 NIXPACKS,dockerfilePath 仅适用于 DOCKERFILE;无权限或未链接项目会报错,需先运行 railway link。提交信息应保持一句话以内。