Railway deploy

Railway 部署指南

概述

Railway.app 是一个免费（有额度限制）的云平台，可以托管 Node.js、Python 等应用。适合个人项目、Demo、原型系统部署。

部署前准备

1. 确保 package.json 包含依赖声明

Railway 需要通过 package.json 知道要安装哪些包。必须在 dependencies 中声明所有依赖：

{
  "name": "your-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node server/index.js",
    "build": "npm install"
  },
  "main": "server/index.js",
  "dependencies": {
    "express": "^5.2.1",
    "better-sqlite3": "^12.9.0",
    "bcryptjs": "^3.0.3",
    "cors": "^2.8.6",
    "express-session": "^1.19.0",
    "xlsx": "^0.18.5"
  }
}

常见错误：本地 npm install 后能运行，但 Railway 报 Cannot find package 'express'。原因：package.json 缺少 dependencies 字段。

2. 创建 Dockerfile（推荐）

在项目根目录创建 Dockerfile（无后缀，大写D）：

FROM node:22-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["node", "server/index.js"]

3. 创建 railway.json 配置

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "DOCKERFILE"
  },
  "deploy": {
    "startCommand": "node server/index.js"
  }
}

部署流程

步骤 1：推送代码到 GitHub

1. 在 GitHub 创建新仓库：https://github.com/new
2. 本地初始化 Git 并推送：

cd your-project
git init
git add .
git commit -m "initial commit"
git branch -M main
git remote add origin https://github.com/你的用户名/仓库名.git
git push -u origin main

步骤 2：连接 Railway

1. 打开 https://railway.app
2. 用 GitHub 账号登录
3. 点 New Project → Deploy from GitHub repo
4. 选择你的仓库
5. Railway 会自动检测并开始部署

步骤 3：获取公网域名

1. 进入项目页面
2. 点进服务（Service）
3. 点 Settings 标签
4. 找 Domains 区域
5. 点 Generate Domain
6. 获得类似 your-app.up.railway.app 的域名

常见问题与解决方案

问题 1：Cannot find package 'express'

原因：package.json 没有声明依赖

解决：在 GitHub 上编辑 package.json，添加 dependencies 字段（见上文）

问题 2：npm install 报错 "npm: not found"

原因：Railway 未正确识别为 Node.js 项目

解决：添加 Dockerfile 和 railway.json（见上文），明确指定构建方式

问题 3：JSON 格式错误

原因：手动编辑 package.json 时漏了逗号或括号

解决：使用 JSON 校验工具检查，确保格式正确

问题 4：NIXPACKS 构建失败

原因：Railway 平台问题或 NIXPACKS bug

解决：改用 Dockerfile 构建（见上文）

问题 5：Railway 平台故障

表现：部署卡住、报错、显示 "Builds may be slow"

解决：查看 Railway Status 页面，等待平台恢复后再 Redeploy

注意事项

1. SQLite 数据不持久：Railway 免费版重启后文件系统会重置。如需持久化数据，需使用外部数据库（如 Turso、PlanetScale）

2. 域名固定：生成的域名不会自动变化，除非手动删除项目

3. 免费额度：Railway 每月提供 $5 免费额度，小型项目够用

4. Redeploy 方法：修改 GitHub 代码会自动触发部署，或手动点 Deployments → Redeploy

资源文件

• references/checklist.md - 部署检查清单