启动 Rails 项目的核心流程是「环境准备 → 依赖安装 → 数据库配置 → 启动服务」，以下是针对 本地开发环境（尤其适配你之前的 macOS 系统）的详细步骤，覆盖从新手到进阶的全场景：

一、启动前的基础准备（必做）

确保你的环境已满足 Rails 运行要求，否则会启动失败：

1. 检查核心依赖是否安装

打开终端，输入以下命令验证：

# 检查 Ruby 版本（Rails 7 要求 Ruby ≥ 2.7.0；Rails 6 要求 ≥ 2.5.0）
ruby -v

# 检查 Rails 版本（确认已安装 Rails）
rails -v

# 检查数据库（Rails 默认用 SQLite3，若用 MySQL/PostgreSQL 需额外安装）
# SQLite3（macOS 自带，无需额外操作）
sqlite3 --version

# 若用 MySQL：检查是否安装
mysql --version

# 若用 PostgreSQL：检查是否安装
psql --version

• 若缺少依赖：
  • Ruby 安装：用 rbenv 或 rvm（推荐 rbenv：brew install rbenv，再安装对应 Ruby 版本）
  • Rails 安装：gem install rails
  • MySQL/PostgreSQL：用 Homebrew 安装（brew install mysql 或 brew install postgresql）

2. 进入项目目录

终端切换到你的 Rails 项目根目录（关键！必须在项目根目录执行启动命令）：

# 示例：cd 到你的项目路径（替换为实际路径）
cd ~/Documents/rails_projects/your_project_name

3. 安装项目依赖

Rails 项目的依赖（Gem）记录在 Gemfile 中，首次启动或拉取他人项目后，必须执行：

# 安装所有依赖（若提示权限问题，可加 --user-install，或用 rbenv 管理 Ruby 版本避免权限问题）
bundle install

• 若报错「Gemfile.lock 冲突」：删除 Gemfile.lock 后重新执行 bundle install
• 若提示「缺少 bundle」：执行 gem install bundler 安装

二、数据库配置与初始化（核心步骤）

Rails 项目启动依赖数据库（默认 SQLite3，无需额外配置；若用 MySQL/PostgreSQL 需手动配置）：

1. 配置数据库连接（仅非 SQLite3 需做）

打开项目中的 config/database.yml 文件，修改对应数据库的配置（以 MySQL 为例）：

development:
  adapter: mysql2
  encoding: utf8mb4
  database: your_project_name_development # 数据库名（自动创建）
  username: root # 你的 MySQL 用户名（默认 root）
  password: your_mysql_password # 你的 MySQL 密码（若未设置则留空）
  host: localhost
  port: 3306

• PostgreSQL 类似，修改 adapter: postgresql，并配置 username/password

2. 创建并初始化数据库

终端执行以下命令，自动创建数据库、执行迁移文件：

# 1. 创建数据库（根据 database.yml 配置创建对应环境的数据库）
rails db:create

# 2. 执行数据库迁移（创建表结构，若项目有 db/migrate 文件必做）
rails db:migrate

# 3. （可选）填充测试数据（若项目有种子文件 db/seeds.rb）
rails db:seed

• 若报错「数据库连接失败」：检查 database.yml 配置是否正确，或数据库服务是否启动（MySQL：brew services start mysql；PostgreSQL：brew services start postgresql）

三、启动 Rails 服务（核心命令）

完成以上准备后，终端执行以下命令启动服务：

1. 基础启动命令（最常用）

# 完整命令
rails server

# 简写（推荐，效果一致）
rails s

• 启动成功后，终端会显示类似日志：
  => Booting Puma
=> Rails 7.1.3 application starting in development
=> Run bin/rails server --help for more startup options
Puma starting in single mode...
* Puma version: 6.4.2 (ruby 3.2.2-p53) ("The Eagle of Durango")
* Min threads: 5, max threads: 5
* Environment: development
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000

2. 访问项目

打开浏览器，输入以下地址即可访问你的 Rails 项目：

http://localhost:3000

• 若看到 Rails 欢迎页面（或你的项目首页），说明启动成功！

四、常用启动参数（进阶需求）

根据开发场景，可添加参数自定义启动方式：

1. 修改端口（默认 3000，避免端口占用）

# 示例：指定端口 3001 启动
rails s -p 3001

# 或
rails server --port 3001

2. 允许局域网访问（比如手机/其他电脑访问本地项目）

# 绑定所有网卡，局域网内其他设备可通过你的 IP:端口 访问
rails s -b 0.0.0.0

# 示例：绑定 IP + 自定义端口
rails s -b 0.0.0.0 -p 3002

• 查看本地 IP：终端输入 ifconfig 或 ipconfig getifaddr en0（macOS），比如 IP 是 192.168.1.100，其他设备访问 http://192.168.1.100:3002

3. 启动生产环境（不推荐本地用，仅测试时）

# 先设置环境变量，再启动（生产环境需提前配置数据库、资产预编译）
RAILS_ENV=production rails s

4. 热重载（Rails 7+ 自带，修改代码无需重启服务）

Rails 7 开发环境默认启用 importmap 或 jsbundling，配合 rails s 即可实现热重载（修改视图、控制器代码后，刷新浏览器生效）。

• 若用 Rails 6 及以下：可安装 spring gem 实现热重载：bundle add spring，之后启动时自动生效。

五、常见启动失败问题排查

1. 端口被占用（报错「Address already in use - bind(2) for “127.0.0.1” port 3000」）

• 方案 1：换端口启动（rails s -p 3001）

• 方案 2：杀死占用端口的进程（macOS/Linux）：

  # 查找占用 3000 端口的进程 PID
  lsof -i :3000
  
  # 杀死进程（替换 PID 为实际数字，比如 1234）
  kill -9 1234
  

2. 数据库迁移失败（报错「Migrations are pending」）

• 执行 rails db:migrate 重新运行迁移
• 若迁移文件冲突，可回滚迁移：rails db:rollback，修复后再重新迁移

3. 依赖缺失（报错「Could not find gem ‘xxx’ in any of the gem sources」）

• 重新执行 bundle install，确保依赖安装完整
• 若仍失败，删除 Gemfile.lock 后再执行 bundle install

4. 数据库服务未启动（报错「Can’t connect to MySQL server on ‘localhost’」）

• 启动数据库服务：
  MySQL：brew services start mysql
  PostgreSQL：brew services start postgresql
  SQLite3：无需启动，默认可用

六、停止 Rails 服务

终端中按 Ctrl + C 即可停止服务（终端会显示 Exiting 表示停止成功）。

总结：启动流程速记

1. 进入项目目录：cd your_project_path
2. 安装依赖：bundle install
3. 数据库初始化：rails db:create && rails db:migrate
4. 启动服务：rails s
5. 浏览器访问：http://localhost:3000