Railway CLI 新建项目与服务指南：快速部署应用与数据库

new by railwayapp/railway-skills

786 周安装量

209 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/railwayapp/railway-skills --skill new

自动化云服务开发运维

🇨🇳中文介绍

新建项目 / 服务 / 数据库

使用正确的配置创建 Railway 项目、服务和数据库。

使用时机

用户说“部署到 railway”（如果已链接则添加服务，否则初始化）
用户说“创建一个 railway 项目”、“初始化”、“新项目”（明确要求新项目）
用户说“链接到 railway”、“连接到 railway”
用户说“创建一个服务”、“添加一个后端”、“新的 api 服务”
用户说“创建一个 vite 应用”、“创建一个 react 网站”、“制作一个 python api”
用户说“从 github.com/用户/仓库部署”、“从这个仓库创建服务”
用户说“添加 postgres”、“添加一个数据库”、“添加 redis”、“添加 mysql”、“添加 mongo”
用户说“连接到 postgres”、“连接数据库”、“将我的 api 连接到 redis”
用户说“添加 postgres 并连接到服务器”
同时设置代码和 Railway 服务

前提条件

检查 CLI 是否已安装：

command -v railway

如果未安装：

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

检查是否已认证：

railway whoami --json

如果未认证：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

初始化与链接决策

如果已链接则跳过此部分 - 只需添加服务即可。

仅当没有项目链接时（直接或通过父目录）才使用此部分。

检查用户的项目

输出可能很大。在子代理中运行并仅提取：

项目 id 和 name
工作区 id 和 name

railway list --json

用户明确说“新项目” → 使用 railway init
用户命名了一个现有项目 → 使用 railway link
目录名称与现有项目匹配 → 询问：链接现有项目还是创建新项目？
没有匹配的项目 → 使用 railway init
不明确 → 询问用户

railway init -n <名称>

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

如果用户有多个工作区，railway init 需要 --workspace 标志。

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

railway whoami --json

workspaces 数组包含每个工作区的 { id, name }。

从用户输入推断工作区： 如果用户说“部署到 xxx 工作区”或“在 my-team 中创建项目”，则将名称与工作区数组匹配并使用相应的 ID：

# 用户说：“在我的个人工作区中创建一个项目”
railway whoami --json | jq '.workspaces[] | select(.name | test("personal"; "i"))'
# 使用匹配的 ID：railway init -n myapp --workspace <匹配的id>

railway link -p <项目>

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

项目链接后，创建服务：

railway add --service <名称>

对于 GitHub 仓库源：创建一个空服务，然后调用 environment 技能通过暂存更改 API 配置源。不要使用 railway add --repo - 它需要 GitHub 应用集成，这通常会失败。

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

基于项目类型进行配置

参考 railpack.md 获取构建配置。参考 monorepo.md 获取 monorepo 模式。

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

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

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

验证 package.json 中存在 start 脚本
如果需要自定义启动：调用 environment 技能设置 startCommand

Python（FastAPI、Django、Flask）：

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

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

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

隔离式 monorepo（应用不共享代码）：

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

共享式 monorepo（TypeScript 工作区、共享包）：

不要设置根目录
设置自定义构建/启动命令以筛选包：
- pnpm：pnpm --filter <包> build
- npm：npm run build --workspace=packages/<包>
- yarn：yarn workspace <包> build
- Turborepo：turbo run build --filter=<包>
设置监视路径以防止不必要的重新构建

详细模式请参阅 monorepo.md。

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

检查现有项目文件：

package.json → Node.js 项目
requirements.txt、pyproject.toml → Python 项目
go.mod → Go 项目
Cargo.toml → Rust 项目
index.html → 静态站点
无 → 指导搭建

Monorepo 检测：

pnpm-workspace.yaml → pnpm 工作区（共享式 monorepo）
带有 workspaces 字段的 package.json → npm/yarn 工作区（共享式 monorepo）
turbo.json → Turborepo（共享式 monorepo）
多个具有独立 package.json 但无工作区配置的子目录 → 隔离式 monorepo

如果不存在代码，请从 railpack.md 建议最小模式：

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

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

npm create astro@latest

Python FastAPI：

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

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

对于添加数据库（Postgres、Redis、MySQL、MongoDB），请使用 database 技能。

database 技能处理：

创建数据库服务
连接变量引用
将服务连接到数据库

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

Railway CLI 未安装。使用以下命令安装：
  npm install -g @railway/cli
或
  brew install railway

未登录到 Railway。运行：railway login

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

项目名称已存在

项目名称已存在。请选择：
- 链接到现有项目：railway link -p <名称>
- 使用其他名称：railway init -n <其他名称>

服务名称已存在

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

创建 HTML 静态站点

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

1. 检查状态 → 未链接
2. railway init -n my-site
3. 指导：创建 index.html
4. railway add --service my-site
5. 无需配置（根目录下的 index.html 自动检测）
6. 使用 deploy 技能：railway up
7. 使用 domain 技能获取公共 URL

创建 Vite React 服务

用户：“创建一个 vite react 服务”

1. 检查状态 → 已链接（或先初始化/链接）
2. 搭建：npm create vite@latest frontend -- --template react
3. railway add --service frontend
4. 无需配置（Vite dist 输出自动检测）
5. 使用 deploy 技能：railway up

向项目添加 Python API

用户：“向我的项目添加一个 python api”

1. 检查状态 → 已链接
2. 指导：创建包含 FastAPI 的 main.py，requirements.txt
3. railway add --service api
4. 无需配置（FastAPI 自动检测）
5. 使用 deploy 技能

链接并添加服务

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

1. railway list --json → 找到“backend”
2. railway link -p backend
3. railway add --service worker
4. 基于 worker 类型指导设置

部署到 Railway（不明确）

用户：“部署到 railway”

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

向隔离式 Monorepo 添加服务

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

1. 检查：/frontend 有自己的 package.json，无工作区配置
2. 这是隔离式 monorepo → 使用根目录
3. railway add --service frontend
4. 调用 environment 技能设置 rootDirectory：/frontend
5. 设置监视路径：/frontend/**

向 TypeScript Monorepo 添加服务

用户：“向这个 turborepo 添加一个新的 api 包”

1. 检查：存在 turbo.json，存在 pnpm-workspace.yaml
2. 这是共享式 monorepo → 使用自定义命令，**不要**设置根目录
3. 指导：创建包含 package.json 的 packages/api
4. railway add --service api
5. 调用 environment 技能设置 buildCommand 和 startCommand（**不要**设置 rootDirectory）
6. 设置监视路径：/packages/api/**，/packages/shared/**

部署现有的 pnpm 工作区包

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

1. 检查：存在 pnpm-workspace.yaml → 共享式 monorepo
2. railway add --service backend
3. 调用 environment 技能设置 buildCommand 和 startCommand
4. 为 backend 和任何共享依赖设置监视路径

部署已链接项目的子目录

用户：“在我的 my-app 目录中创建一个 vite 应用并部署到 railway”
CWD：~/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. 调用 environment 技能设置 rootDirectory：/my-app
8. 从根目录部署：railway up

🇺🇸English

New Project / Service / Database

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

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

Prerequisites

Check CLI installed:

command -v railway

If not installed:

Install Railway CLI:

npm install -g @railway/cli

brew install railway

Check authenticated:

railway whoami --json

If not authenticated:

Run railway login to authenticate.

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

Check Current State

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)

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

Parent Directory Linking

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

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.

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

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

Create New Project

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)

Multiple Workspaces

If the user has multiple workspaces, railway init requires the --workspace flag.

Get workspace IDs from:

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:

# 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>

Link Existing Project

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

Create Service

After project is linked, create a service:

railway add --service <name>

For GitHub repo sources : Create an empty service, then invoke the 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 environment skill to set source.repo and source.branch
Apply changes to trigger deployment

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

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.

Project Setup Guidance

Analyze the codebase to ensure Railway compatibility.

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

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:

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

Astro:

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.

Databases

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

The database skill handles:

Creating database services
Connection variable references
Wiring services to databases

Composability

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

Error Handling

CLI Not Installed

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

Not Authenticated

Not logged in to Railway. Run: railway login

No Workspaces

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

Project Name Taken

Project name already exists. Either:
- Link to existing: railway link -p <name>
- Use different 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>

Examples

Create HTML Static Site

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

Create Vite React Service

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

Add Python API to Project

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

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

Deploy to Railway (Ambiguous)

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?"

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/**

Add Service to TypeScript Monorepo

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/**

Deploy Existing pnpm Workspace Package

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

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

Weekly Installs

786

Repository

railwayapp/rail…y-skills

GitHub Stars

209

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode662

codex651

gemini-cli615

github-copilot592

claude-code591

amp539