railway-new

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

New Project / Service / Database

新建项目/服务/数据库

Create Railway projects, services, and databases with proper configuration.

创建配置合理的Railway项目、服务和数据库。

When to Use

适用场景

User says "deploy to railway" (add service if linked, init if not)
User says "create a railway project", "init", "new project" (explicit new project)
User says "link to railway", "connect to railway"
User says "create a service", "add a backend", "new api service"
User says "create a vite app", "create a react website", "make a python api"
User says "deploy from github.com/user/repo", "create service from this repo"
User says "add postgres", "add a database", "add redis", "add mysql", "add mongo"
User says "connect to postgres", "wire up the database", "connect my api to redis"
User says "add postgres and connect to the server"
Setting up code + Railway service together

用户提及“deploy to railway”（若已关联则添加服务，未关联则初始化）
用户提及“create a railway project”“init”“new project”（明确要求新建项目）
用户提及“link to railway”“connect to railway”
用户提及“create a service”“add a backend”“new api service”
用户提及“create a vite app”“create a react website”“make a python api”
用户提及“deploy from github.com/user/repo”“create service from this repo”
用户提及“add postgres”“add a database”“add redis”“add mysql”“add mongo”
用户提及“connect to postgres”“wire up the database”“connect my api to redis”
用户提及“add postgres and connect to the server”
同时设置代码与Railway服务

Prerequisites

前置条件

Check CLI installed:

bash

command -v railway

If not installed:

Install Railway CLI:
npm install -g @railway/cli
or
brew install railway

Check authenticated:

bash

railway whoami --json

If not authenticated:

Run
railway login
to authenticate.

检查CLI是否已安装：

bash

command -v railway

若未安装：

安装Railway CLI：
npm install -g @railway/cli
或
brew install railway

检查是否已认证：

bash

railway whoami --json

若未认证：

运行
railway login
进行认证。

Decision Flow

决策流程

railway status --json (in current dir)
     │
┌────┴────┐
Linked    Not Linked
  │            │
  │       Check parent: cd .. && railway status --json
  │            │
  │       ┌────┴────┐
  │    Parent      Not linked
  │    Linked      anywhere
  │       │            │
  │   Add service   railway list
  │   Set rootDir      │
  │   Deploy       ┌───┴───┐
  │       │      Match?  No match
  │       │        │        │
  │       │      Link    Init new
  └───────┴────────┴────────┘
           │
    User wants service?
           │
     ┌─────┴─────┐
    Yes         No
     │           │
Scaffold code   Done
     │
railway add --service
     │
Configure if needed
     │
Ready to deploy

railway status --json (当前目录下)
     │
┌────┴────┐
已关联    未关联
  │            │
  │       检查父目录：cd .. && railway status --json
  │            │
  │       ┌────┴────┐
  │    父目录已关联      未关联
  │                    任何位置
  │       │            │
  │   添加服务   railway list
  │   设置rootDir      │
  │   部署       ┌───┴───┐
  │       │      匹配？  不匹配
  │       │        │        │
  │       │      关联    初始化新项目
  └───────┴────────┴────────┘
           │
    用户是否需要服务？
           │
     ┌─────┴─────┐
    是         否
     │           │
生成代码框架   完成
     │
railway add --service
     │
按需配置
     │
准备部署

Check Current State

检查当前状态

bash

railway status --json

If linked: Add a service to the existing project (see below)
If not linked: Check if a PARENT directory is linked (see below)

bash

railway status --json

已关联：向现有项目添加服务（见下文）
未关联：检查父目录是否已关联（见下文）

When Already Linked

已关联时的操作

Default behavior: "deploy to railway" = add a service to the linked project.

Do NOT create a new project unless user EXPLICITLY says:

"new project", "create a project", "init a project"
"separate project", "different project"

App names like "flappy-bird" or "my-api" are SERVICE names, not project names.

User: "create a vite app called foo and deploy to railway"
Project: Already linked to "my-project"

WRONG: railway init -n foo
RIGHT: railway add --service foo

默认行为：“deploy to railway” = 向已关联项目添加服务。

除非用户明确提及以下内容，否则不要创建新项目：

“new project”“create a project”“init a project”
“separate project”“different project”

类似“flappy-bird”或“my-api”的名称是服务名称，而非项目名称。

用户：“创建名为foo的Vite应用并部署到Railway”
项目：已关联到“my-project”

错误操作：railway init -n foo
正确操作：railway add --service foo

Parent Directory Linking

父目录关联

Railway CLI walks up the directory tree to find a linked project. If you're in a subdirectory:

bash

cd .. && railway status --json

If parent is linked, you don't need to init/link the subdirectory. Instead:

Create service:
```
railway add --service <name>
```
Set
```
rootDirectory
```
to subdirectory path via environment skill
Deploy from root:
```
railway up
```

If no parent is linked, proceed with init or link flow.

Railway CLI会遍历目录树查找已关联项目。若当前处于子目录：

bash

cd .. && railway status --json

若父目录已关联，无需初始化/关联子目录，而是：

创建服务：
```
railway add --service <name>
```
通过环境技能设置
```
rootDirectory
```
为子目录路径
从根目录部署：
```
railway up
```

若父目录未关联，继续执行初始化或关联流程。

Init vs Link Decision

初始化与关联的决策

Skip this section if already linked - just add a service instead.

Only use this section when NO project is linked (directly or via parent).

若已关联则跳过此部分 - 直接添加服务即可。

仅当没有任何项目（直接或通过父目录）关联时使用此部分。

Check User's Projects

检查用户的项目

The output can be large. Run in a subagent and extract only:

Project
```
id
```
and
```
name
```
Workspace
```
id
```
and
```
name
```

bash

railway list --json

输出内容可能较多。在子代理中运行并仅提取以下信息：

项目
```
id
```
和
```
name
```
工作区
```
id
```
和
```
name
```

bash

railway list --json

Decision Logic

决策逻辑

User explicitly says "new project" → Use
```
railway init
```
User names an existing project → Use
```
railway link
```
Directory name matches existing project → Ask: link existing or create new?
No matching projects → Use
```
railway init
```
Ambiguous → Ask user

用户明确说“new project” → 使用
```
railway init
```
用户指定现有项目名称 → 使用
```
railway link
```
目录名称与现有项目匹配 → 询问用户：关联现有项目还是创建新项目？
无匹配项目 → 使用
```
railway init
```
模糊需求 → 询问用户

Create New Project

新建项目

bash

railway init -n <name>

Options:

```
-n, --name
```
- Project name (auto-generated if omitted in non-interactive mode)
```
-w, --workspace
```
- Workspace name or ID (required if multiple workspaces exist)

bash

railway init -n <name>

选项：

```
-n, --name
```
- 项目名称（非交互模式下若省略则自动生成）
```
-w, --workspace
```
- 工作区名称或ID（若存在多个工作区则为必填项）

Multiple Workspaces

多工作区场景

If the user has multiple workspaces,

railway init

requires the

--workspace

flag.

Get workspace IDs from:

bash

railway whoami --json

The

workspaces

array contains

{ id, name }

for each workspace.

Inferring workspace from user input: If user says "deploy into xxx workspace" or "create project in my-team", match the name against the workspaces array and use the corresponding ID:

bash

undefined

若用户有多个工作区，

railway init

需要

--workspace

参数。

从以下命令获取工作区ID：

bash

railway whoami --json

workspaces

数组包含每个工作区的

{ id, name }

。

从用户输入推断工作区： 若用户说“deploy into xxx workspace”或“create project in my-team”，将名称与workspaces数组匹配，并使用对应的ID：

bash

undefined

User says: "create a project in my personal workspace"

用户说：“在我的个人工作区创建项目”

railway whoami --json | jq '.workspaces[] | select(.name | test("personal"; "i"))'

Use the matched ID: railway init -n myapp --workspace <matched-id>

使用匹配到的ID：railway init -n myapp --workspace <matched-id>

undefined

undefined

Link Existing Project

关联现有项目

bash

railway link -p <project>

Options:

```
-p, --project
```
- Project name or ID
```
-e, --environment
```
- Environment (default: production)
```
-s, --service
```
- Service to link
```
-t, --team
```
- Team/workspace

bash

railway link -p <project>

选项：

```
-p, --project
```
- 项目名称或ID
```
-e, --environment
```
- 环境（默认：production）
```
-s, --service
```
- 要关联的服务
```
-t, --team
```
- 团队/工作区

Create Service

创建服务

After project is linked, create a service:

bash

railway add --service <name>

For GitHub repo sources: Create an empty service, then invoke the railway-environment skill to configure the source via staged changes API. Do NOT use

railway add --repo

- it requires GitHub app integration which often fails.

Flow:

```
railway add --service my-api
```
Invoke railway-environment skill to set
```
source.repo
```
and
```
source.branch
```
Apply changes to trigger deployment

项目关联后，创建服务：

bash

railway add --service <name>

对于GitHub仓库源：创建空服务，然后调用railway-environment技能通过分阶段变更API配置源。不要使用

railway add --repo

- 它需要GitHub应用集成，经常会失败。

流程：

```
railway add --service my-api
```
调用railway-environment技能设置
```
source.repo
```
和
```
source.branch
```
应用变更以触发部署

Configure Based on Project Type

根据项目类型配置

Reference railpack.md for build configuration. Reference monorepo.md for monorepo patterns.

Static site (Vite, CRA, Astro static):

Railpack auto-detects common output dirs (dist, build)
If non-standard output dir: invoke railway-environment skill to set
```
RAILPACK_STATIC_FILE_ROOT
```
Do NOT use
```
railway variables
```
CLI - always use the environment skill

Node.js SSR (Next.js, Nuxt, Express):

Verify
```
start
```
script exists in package.json
If custom start needed: invoke railway-environment skill to set
```
startCommand
```

Python (FastAPI, Django, Flask):

Verify
```
requirements.txt
```
or
```
pyproject.toml
```
exists
Auto-detected by Railpack, usually no config needed

Go:

Verify
```
go.mod
```
exists
Auto-detected, no config needed

参考railpack.md进行构建配置。参考monorepo.md了解单仓库模式。

静态站点（Vite、CRA、Astro静态）：

Railpack会自动检测常见输出目录（dist、build）
若输出目录非标准：调用railway-environment技能设置
```
RAILPACK_STATIC_FILE_ROOT
```
不要使用
```
railway variables
```
CLI - 始终使用环境技能

Node.js SSR（Next.js、Nuxt、Express）：

验证package.json中是否存在
```
start
```
脚本
若需要自定义启动命令：调用railway-environment技能设置
```
startCommand
```

Python（FastAPI、Django、Flask）：

验证是否存在
```
requirements.txt
```
或
```
pyproject.toml
```
Railpack会自动检测，通常无需配置

Go：

验证是否存在
```
go.mod
```
自动检测，无需配置

Monorepo Configuration

单仓库配置

Critical decision: Root directory vs custom commands.

Isolated monorepo (apps don't share code):

Set Root Directory to the app's subdirectory (e.g.,
```
/frontend
```
)
Only that directory's code is available during build

Shared monorepo (TypeScript workspaces, shared packages):

Do NOT set root directory

Set custom build/start commands to filter the package:

pnpm:
```
pnpm --filter <package> build
```

npm:

npm run build --workspace=packages/<package>

yarn:
```
yarn workspace <package> build
```
Turborepo:
```
turbo run build --filter=<package>
```

Set watch paths to prevent unnecessary rebuilds

See monorepo.md for detailed patterns.

关键决策：根目录 vs 自定义命令。

独立单仓库（应用之间不共享代码）：

将根目录设置为应用的子目录（例如
```
/frontend
```
）
构建期间仅可访问该目录下的代码

共享单仓库（TypeScript工作区、共享包）：

设置自定义构建/启动命令以过滤包：

pnpm:
```
pnpm --filter <package> build
```

npm:

npm run build --workspace=packages/<package>

yarn:
```
yarn workspace <package> build
```
Turborepo:
```
turbo run build --filter=<package>
```

设置监听路径以避免不必要的重建

详细模式请参考monorepo.md。

Project Setup Guidance

项目搭建指南

Analyze the codebase to ensure Railway compatibility.

分析代码库以确保与Railway兼容。

Analyze Codebase

分析代码库

Check for existing project files:

```
package.json
```
→ Node.js project
```
requirements.txt
```
,
```
pyproject.toml
```
→ Python project
```
go.mod
```
→ Go project
```
Cargo.toml
```
→ Rust project
```
index.html
```
→ Static site
None → Guide scaffolding

Monorepo detection:

```
pnpm-workspace.yaml
```
→ pnpm workspace (shared monorepo)
```
package.json
```
with
```
workspaces
```
field → npm/yarn workspace (shared monorepo)
```
turbo.json
```
→ Turborepo (shared monorepo)
Multiple subdirs with separate
```
package.json
```
but no workspace config → isolated monorepo

检查现有项目文件：

```
package.json
```
→ Node.js项目
```
requirements.txt
```
、
```
pyproject.toml
```
→ Python项目
```
go.mod
```
→ Go项目
```
Cargo.toml
```
→ Rust项目
```
index.html
```
→ 静态站点
无上述文件 → 引导生成代码框架

单仓库检测：

```
pnpm-workspace.yaml
```
→ pnpm工作区（共享单仓库）
包含
```
workspaces
```
字段的
```
package.json
```
→ npm/yarn工作区（共享单仓库）
```
turbo.json
```
→ Turborepo（共享单仓库）
多个子目录包含独立的
```
package.json
```
但无工作区配置 → 独立单仓库

Scaffolding Hints

代码框架生成提示

If no code exists, suggest minimal patterns from railpack.md:

Static site:

Create an
index.html
file in the root directory.

Vite React:

bash

npm create vite@latest . -- --template react

Astro:

bash

npm create astro@latest

Python FastAPI:

Create
main.py
with FastAPI app and
requirements.txt
with dependencies.

Go:

Create
main.go
with HTTP server listening on
PORT
env var.

若不存在代码，建议从railpack.md中选择最简模式：

静态站点：

在根目录创建
index.html
文件。

Vite React：

bash

npm create vite@latest . -- --template react

Astro：

bash

npm create astro@latest

Python FastAPI：

创建包含FastAPI应用的
main.py
和包含依赖的
requirements.txt
。

Go：

创建监听
PORT
环境变量的HTTP服务器
main.go
。

Databases

数据库

For adding databases (Postgres, Redis, MySQL, MongoDB), use the railway-railway-database skill.

The railway-railway-database skill handles:

Creating database services
Connection variable references
Wiring services to databases

添加数据库（Postgres、Redis、MySQL、MongoDB）请使用railway-railway-database技能。

railway-railway-database技能负责：

创建数据库服务
连接变量引用
关联服务与数据库

Composability

组合使用

After service created: Use railway-deploy skill to push code
For advanced config: Use railway-environment skill (buildCommand, startCommand)
For domains: Use railway-domain skill
For status checks: Use railway-status skill
For service operations (rename, delete, status): Use railway-service skill

服务创建后：使用railway-deploy技能推送代码
高级配置：使用railway-environment技能（buildCommand、startCommand）
域名配置：使用railway-domain技能
状态检查：使用railway-status技能
服务操作（重命名、删除、状态）：使用railway-service技能

Error Handling

错误处理

CLI Not Installed

CLI未安装

Railway CLI not installed. Install with:
  npm install -g @railway/cli
or
  brew install railway

未安装Railway CLI。请通过以下方式安装：
  npm install -g @railway/cli
或
  brew install railway

Not Authenticated

未认证

Not logged in to Railway. Run: railway login

未登录Railway。请运行：railway login

No Workspaces

无工作区

No workspaces found. Create one at railway.com or verify authentication.

未找到工作区。请在railway.com创建一个或验证认证状态。

Project Name Taken

项目名称已存在

Project name already exists. Either:
- Link to existing: railway link -p <name>
- Use different name: railway init -n <other-name>

项目名称已存在。请选择：
- 关联现有项目：railway link -p <name>
- 使用其他名称：railway init -n <other-name>

Service Name Taken

服务名称已存在

Service name already exists in this project. Use a different name:
  railway add --service <other-name>

该项目中已存在此服务名称。请使用其他名称：
  railway add --service <other-name>

Examples

示例

Create HTML Static Site

创建HTML静态站点

User: "create a simple html site and deploy to railway"

1. Check status → not linked
2. railway init -n my-site
3. Guide: create index.html
4. railway add --service my-site
5. No config needed (index.html in root auto-detected)
6. Use deploy skill: railway up
7. Use domain skill for public URL

用户：“创建一个简单的HTML站点并部署到Railway”

1. 检查状态 → 未关联
2. railway init -n my-site
3. 引导：创建index.html
4. railway add --service my-site
5. 无需配置（根目录下的index.html会被自动检测）
6. 使用部署技能：railway up
7. 使用域名技能配置公共URL

Create Vite React Service

创建Vite React服务

User: "create a vite react service"

1. Check status → linked (or init/link first)
2. Scaffold: npm create vite@latest frontend -- --template react
3. railway add --service frontend
4. No config needed (Vite dist output auto-detected)
5. Use deploy skill: railway up

用户：“创建一个Vite React服务”

1. 检查状态 → 已关联（或先初始化/关联）
2. 生成框架：npm create vite@latest frontend -- --template react
3. railway add --service frontend
4. 无需配置（Vite的dist输出会被自动检测）
5. 使用部署技能：railway up

Add Python API to Project

向项目添加Python API

User: "add a python api to my project"

1. Check status → linked
2. Guide: create main.py with FastAPI, requirements.txt
3. railway add --service api
4. No config needed (FastAPI auto-detected)
5. Use deploy skill

用户：“向我的项目添加Python API”

1. 检查状态 → 已关联
2. 引导：创建包含FastAPI的main.py和requirements.txt
3. railway add --service api
4. 无需配置（FastAPI会被自动检测）
5. 使用部署技能

Link and Add Service

关联并添加服务

User: "connect to my backend project and add a worker service"

1. railway list --json → find "backend"
2. railway link -p backend
3. railway add --service worker
4. Guide setup based on worker type

用户：“连接到我的后端项目并添加一个Worker服务”

1. railway list --json → 找到“backend”
2. railway link -p backend
3. railway add --service worker
4. 根据Worker类型引导设置

Deploy to Railway (Ambiguous)

部署到Railway（模糊需求）

User: "deploy to railway"

1. railway status → not linked
2. railway list → has projects
3. Directory is "my-app", found project "my-app"
4. Ask: "Found existing project 'my-app'. Link to it or create new?"
5. User: "link"
6. railway link -p my-app
7. Ask: "Create a service for this code?"

用户：“部署到Railway”

1. railway status → 未关联
2. railway list → 存在项目
3. 目录名为“my-app”，找到项目“my-app”
4. 询问：“找到现有项目'my-app'。关联它还是创建新项目？”
5. 用户：“关联”
6. railway link -p my-app
7. 询问：“为此代码创建服务？”

Add Service to Isolated Monorepo

向独立单仓库添加服务

User: "create a static site in the frontend directory"

1. Check: /frontend has its own package.json, no workspace config
2. This is isolated monorepo → use root directory
3. railway add --service frontend
4. Invoke environment skill to set rootDirectory: /frontend
5. Set watch paths: /frontend/**

用户：“在frontend目录创建静态站点”

1. 检查：/frontend有独立的package.json，无工作区配置
2. 这是独立单仓库 → 使用根目录
3. railway add --service frontend
4. 调用环境技能设置rootDirectory: /frontend
5. 设置监听路径：/frontend/**

Add Service to TypeScript Monorepo

向TypeScript单仓库添加服务

User: "add a new api package to this turborepo"

1. Check: turbo.json exists, pnpm-workspace.yaml exists
2. This is shared monorepo → use custom commands, NOT root directory
3. Guide: create packages/api with package.json
4. railway add --service api
5. Invoke environment skill to set buildCommand and startCommand (do NOT set rootDirectory)
6. Set watch paths: /packages/api/**, /packages/shared/**

用户：“向这个Turborepo添加新的API包”

1. 检查：存在turbo.json、pnpm-workspace.yaml
2. 这是共享单仓库 → 使用自定义命令，不要设置根目录
3. 引导：创建packages/api并添加package.json
4. railway add --service api
5. 调用环境技能设置buildCommand和startCommand（不要设置rootDirectory）
6. 设置监听路径：/packages/api/**, /packages/shared/**

Deploy Existing pnpm Workspace Package

部署现有pnpm工作区包

User: "deploy the backend package to railway"

1. Check: pnpm-workspace.yaml exists → shared monorepo
2. railway add --service backend
3. Invoke environment skill to set buildCommand and startCommand
4. Set watch paths for backend + any shared deps

用户：“将backend包部署到Railway”

1. 检查：存在pnpm-workspace.yaml → 共享单仓库
2. railway add --service backend
3. 调用环境技能设置buildCommand和startCommand
4. 设置backend及所有共享依赖的监听路径

Deploy Subdirectory of Linked Project

部署已关联项目的子目录

User: "create a vite app in my-app directory and deploy to railway"
CWD: ~/projects/my-project/my-app (parent already linked to "my-project")

1. Check status in my-app → not linked
2. Check parent: cd .. && railway status → IS linked to "my-project"
3. DON'T init/link the subdirectory
4. Scaffold: bun create vite my-app --template react-ts
5. cd my-app && bun install
6. railway add --service my-app
7. Invoke environment skill to set rootDirectory: /my-app
8. Deploy from root: railway up

用户：“在my-app目录创建Vite应用并部署到Railway”
当前工作目录：~/projects/my-project/my-app（父目录已关联到“my-project”）

1. 检查my-app目录状态 → 未关联
2. 检查父目录：cd .. && railway status → 已关联到“my-project”
3. 不要初始化/关联子目录
4. 生成框架：bun create vite my-app --template react-ts
5. cd my-app && bun install
6. railway add --service my-app
7. 调用环境技能设置rootDirectory: /my-app
8. 从根目录部署：railway up