railway-environment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Environment Configuration

环境配置

Query, stage, and apply configuration changes for Railway environments.

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

Shell Escaping

Shell转义

CRITICAL: When running GraphQL queries via bash, you MUST wrap in heredoc to prevent shell escaping issues:

bash

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

Without the heredoc wrapper, multi-line commands break and exclamation marks in GraphQL non-null types get escaped, causing query failures.

**重要提示：**通过bash运行GraphQL查询时，必须使用here-doc包裹以避免Shell转义问题：

bash

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

如果不使用here-doc包裹，多行命令会失效，且GraphQL非空类型中的感叹号会被转义，导致查询失败。

When to Use

使用场景

User wants to create a new environment
User wants to duplicate an environment (e.g., "copy production to staging")
User wants to switch to a different environment
User asks about current build/deploy settings, variables, replicas, health checks, domains
User asks to change service source (Docker image, branch, commit, root directory)
User wants to connect a service to a GitHub repo
User wants to deploy from a GitHub repo (create empty service first via railway-new skill, then use this)
User asks to change build or start command
User wants to add/update/delete environment variables
User wants to change replica count or configure health checks
User asks to delete a service, volume, or bucket
User says "apply changes", "commit changes", "deploy changes"
Auto-fixing build errors detected in logs

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

Create Environment

创建环境

Create a new environment in the linked project:

bash

railway environment new <name>

Duplicate an existing environment:

bash

railway environment new staging --duplicate production

With service-specific variables:

bash

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

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

bash

railway environment new <name>

复制现有环境：

bash

railway environment new staging --duplicate production

包含服务特定变量：

bash

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

Switch Environment

切换环境

Link a different environment to the current directory:

bash

railway environment <name>

Or by ID:

bash

railway environment <environment-id>

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

bash

railway environment <name>

或通过ID切换：

bash

railway environment <environment-id>

Get Context

获取上下文

bash

railway status --json

Extract:

```
project.id
```
- for service lookup
```
environment.id
```
- for the mutations
```
service.id
```
- default service if user doesn't specify one

bash

railway status --json

提取信息：

```
project.id
```
- 用于服务查找
```
environment.id
```
- 用于变更操作
```
service.id
```
- 用户未指定时的默认服务

Resolve Service ID

解析服务ID

If user specifies a service by name, query project services:

graphql

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

Match the service name (case-insensitive) to get the service ID.

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

graphql

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

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

Query Configuration

查询配置

Fetch current environment configuration and staged changes.

graphql

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

Example:

bash

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

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

graphql

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

示例：

bash

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

Response Structure

响应结构

The

config

field contains current configuration:

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

The

patch

field in

environmentStagedChanges

contains pending changes. The effective configuration is the base

config

merged with the staged

patch

For complete field reference, see reference/environment-config.md.

For variable syntax and service wiring patterns, see reference/variables.md.

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

environmentStagedChanges

中的

patch

字段包含待处理的变更。最终生效的配置是基础

config

与暂存

patch

的合并结果。

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

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

Get Rendered Variables

获取渲染后的变量

The GraphQL queries above return unrendered variables - template syntax like

${{shared.DOMAIN}}

is preserved. This is correct for management/editing.

To see rendered (resolved) values as they appear at runtime:

bash

undefined

上述GraphQL查询返回的是未渲染的变量 - 保留了

${{shared.DOMAIN}}

这类模板语法。这对于管理/编辑操作是正确的。

要查看运行时的**渲染后（解析完成）**的值：

bash

undefined

Current linked service

当前关联的服务

railway variables --json

Specific service

指定服务

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


**When to use:**
- Debugging connection issues (see actual URLs/ports)
- Verifying variable resolution is correct
- Viewing Railway-injected values (RAILWAY_*)

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


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

Stage Changes

暂存变更

Stage configuration changes via the

environmentStageChanges

mutation. Use

merge: true

to automatically merge with existing staged changes.

graphql

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

Important: Always use variables (not inline input) because service IDs are UUIDs which can't be used as unquoted GraphQL object keys.

Example:

bash

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

通过

environmentStageChanges

变更操作暂存配置变更。使用

merge: true

自动与现有暂存变更合并。

graphql

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

**重要提示：**始终使用变量（而非内联输入），因为服务ID是UUID，无法作为未加引号的GraphQL对象键。

示例：

bash

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

Delete Service

删除服务

Use

isDeleted: true

bash

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

使用

isDeleted: true

：

bash

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

Stage and Apply Immediately

暂存并立即应用

For single changes that should deploy right away, use

environmentPatchCommit

to stage and apply in one call.

graphql

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

Example:

bash

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

When to use: Single change, no need to batch, user wants immediate deployment.

When NOT to use: Multiple related changes to batch, or user says "stage only" / "don't deploy yet".

对于需要立即部署的单一变更，使用

environmentPatchCommit

一步完成暂存和应用。

graphql

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

示例：

bash

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

**适用场景：**单一变更，无需批量处理，用户要求立即部署。

**不适用场景：**多个相关变更需要批量处理，或用户要求"仅暂存"/"暂不部署"。

Apply Staged Changes

应用暂存的变更

Commit staged changes and trigger deployments.

Note: There is no

railway apply

CLI command. Use the mutation below or direct users to the web UI.

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

**注意：**没有

railway apply

CLI命令。使用下方的变更操作或引导用户前往Web UI。

Apply Mutation

应用变更操作

Mutation name:
environmentPatchCommitStaged

graphql

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

Example:

bash

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

变更操作名称：
environmentPatchCommitStaged

graphql

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

示例：

bash

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

Parameters

参数

Field	Type	Default	Description
`environmentId`	String!	-	Environment ID from status
`message`	String	null	Short description of changes
`skipDeploys`	Boolean	false	Skip deploys (only if user explicitly asks)

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

Commit Message

提交信息

Keep very short - one sentence max. Examples:

"set build command to fix npm error"
"add API_KEY variable"
"increase replicas to 3"

Leave empty if no meaningful description.

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

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

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

Default Behavior

默认行为

Always deploy unless user explicitly asks to skip. Only set

skipDeploys: true

if user says "apply without deploying", "commit but don't deploy", or "skip deploys".

Returns a workflow ID (string) on success.

除非用户明确要求跳过，否则始终部署。仅当用户提到"应用但不部署"、"提交但不部署"或"跳过部署"时，才设置

skipDeploys: true

。

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

Auto-Apply Behavior

自动应用行为

By default, apply changes immediately.

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

Flow

流程

Single change: Use

environmentPatchCommit

to stage and apply in one call.

Multiple changes or batching: Use

environmentStageChanges

with

merge: true

for each change, then

environmentPatchCommitStaged

to apply.

**单一变更：**使用

environmentPatchCommit

一步完成暂存和应用。

**多个变更或批量处理：**对每个变更使用

environmentStageChanges

并设置

merge: true

，然后使用

environmentPatchCommitStaged

应用。

When NOT to Auto-Apply

不自动应用的场景

User explicitly says "stage only", "don't deploy yet", or similar
User is making multiple related changes that should deploy together

When you don't auto-apply, tell the user:

Changes staged. Apply them at: https://railway.com/project/{projectId} Or ask me to apply them.

Get

projectId

from

railway status --json

→

project.id

用户明确要求"仅暂存"、"暂不部署"或类似表述
用户正在进行多个相关变更，需要一起部署

当不自动应用时，告知用户：

变更已暂存。可在此处应用：https://railway.com/project/{projectId} 或告知我以应用变更。

从

railway status --json

的

project.id

获取

projectId

Error Handling

错误处理

Service Not Found

服务未找到

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

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

No Staged Changes

无暂存变更

No patch to apply

There are no staged changes to commit. Stage changes first.

No patch to apply

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

Invalid Configuration

无效配置

Common issues:

```
buildCommand
```
and
```
startCommand
```
cannot be identical
```
buildCommand
```
only valid with NIXPACKS builder
```
dockerfilePath
```
only valid with DOCKERFILE builder

常见问题：

```
buildCommand
```
和
```
startCommand
```
不能相同
```
buildCommand
```
仅在使用NIXPACKS构建器时有效
```
dockerfilePath
```
仅在使用DOCKERFILE构建器时有效

No Permission

无权限

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

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

No Linked Project

无关联项目

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

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

Composability

组合使用

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

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