「环境搭建」使用 Trae 完成 Ruby on Rails 完整环境搭建指南 🚀

Ruby on Rails 完整环境搭建指南 🚀

视频操作：「掌握Trae IDE」 第十一课：别再踩坑了！围巾哥萧尘亲授：Trae+Ruby+Rails 全栈开发环境🧣

基于 macOS 系统的完整 Rails 开发环境配置指南 - 理论与实践结合版

📋 系统环境

• 操作系统: macOS (测试版本: M4 15.5)

• 包管理器: Homebrew

• Ruby版本管理: rbenv (推荐) 或 RVM

• Ruby版本: 3.4.4 或系统默认版本

• Rails版本: 8.0.2

🛠️ 完整安装步骤

1. 安装 Xcode 和 Command Line Tools

安装 Xcode

# 从 App Store 安装 Xcode

# 注意：安装时建议关闭VPN以提高下载速度

# 首次打开需要同意用户协议并输入系统密码

安装 Command Line Tools

# 安装开发者工具

xcode-select --install

  


# 验证安装

xcode-select -p

# 成功会显示：/Applications/Xcode.app/Contents/Developer

2. 安装 Homebrew

# 安装 Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  


# 配置环境变量（针对zsh用户）

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc

source ~/.zshrc

  


# 验证安装

brew --version

注意事项:

• 安装过程中按回车键同意协议

• 输入系统密码时，屏幕不会显示输入内容

3. 安装必要工具

# 安装Git

brew install git

git --version

  


# 安装ImageMagick（图像处理）

brew install imagemagick

  


# 安装PostgreSQL（可选，如需要数据库）

brew install postgresql

psql --version

  


# 启动PostgreSQL服务（可选）

brew services start postgresql

4. 安装 Ruby 版本管理工具

方案A: 使用 rbenv (推荐)

# 安装 rbenv

brew install rbenv

  


# 初始化 rbenv 环境

echo 'eval "$(rbenv init -)"' >> ~/.zshrc

source ~/.zshrc

  


# 验证安装

rbenv --version

方案B: 使用 RVM (备选)

# 安装RVM

\curl -sSL https://get.rvm.io | bash -s stable

  


# 使RVM生效

source ~/.rvm/scripts/rvm

  


# 安装依赖

brew install libxml2

5. 安装和配置 Ruby

使用 rbenv 安装 Ruby

# 方法1: 安装指定版本（如果需要特定版本）

rbenv install 3.4.4

rbenv global 3.4.4

  


# 方法2: 使用系统版本（推荐，避免编译时间）

rbenv global system

  


# 刷新环境

rbenv rehash

  


# 验证配置

rbenv version

which ruby

ruby -v

使用 RVM 安装 Ruby

# 安装Ruby 3.4.4

rvm install 3.4.4

  


# 设置为默认版本

rvm use 3.4.4 --default

  


# 验证安装

ruby -v

6. 配置 Gem 源（重要！）

由于网络原因，强烈建议配置国内镜像源：

# 方法1: 使用 Ruby China 源（推荐）

gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/

  


# 方法2: 如果上述源有问题，可尝试阿里云源

gem sources --add https://mirrors.aliyun.com/rubygems/ --remove https://rubygems.org/

  


# 验证源配置

gem sources -l

7. 安装 Rails

# 安装最新版本的 Rails

gem install rails

  


# 或安装指定版本

gem install rails -v 8.0.2

  


# 验证安装

rails -v

8. 创建和配置 Rails 项目

# 创建新的Rails项目

rails new blog

cd blog

  


# 配置项目Ruby版本（如果使用rbenv）

echo "system" > .ruby-version

# 或指定具体版本

# echo "3.4.4" > .ruby-version

9. 配置项目 Gem 源

编辑项目的 Gemfile 文件，修改第一行：

# 推荐使用 Ruby China 源

source "http://gems.ruby-china.com"

  


# 如果有网络问题，可尝试其他源：

# source "https://mirrors.aliyun.com/rubygems/"

# source "https://rubygems.org"  # 官方源（可能较慢）

10. 安装项目依赖

# 配置 bundle 安装路径到项目本地（推荐）

bundle config set path 'vendor/bundle'

  


# 安装所有依赖包

bundle install

  


# 如果遇到锁定问题，可尝试：

# bundle clean --force

# rm -f .bundle/config

# bundle install

11. 启动开发服务器

# 启动 Rails 开发服务器

bundle exec rails server

  


# 或简写

rails s

服务器启动后，访问 http://127.0.0.1:3000 或 http://localhost:3000 查看应用。

🔧 常见问题及解决方案

问题1: command not found: rbenv

原因: rbenv 未正确安装或环境变量未配置

解决方案:

# 重新安装 rbenv

brew install rbenv

  


# 确保 shell 配置正确

echo 'eval "$(rbenv init -)"' >> ~/.zshrc

source ~/.zshrc

  


# 验证

rbenv --version

问题2: Gem 安装超时或失败

原因: 网络连接问题或源服务器不稳定

解决方案:

1. 更换 gem 源（见上述配置）

2. 检查网络连接

3. 尝试不同的镜像源：

   ```bash

   # Ruby China 源

   source "gems.ruby-china.com"

   

   # 阿里云源

   source "mirrors.aliyun.com/rubygems/"

   

   # 官方源（备用）

   source "rubygems.org"

   ```

问题3: Bundle 锁定问题

原因: 多个 bundle 进程同时运行或异常退出

解决方案:

# 清理 bundle 缓存

bundle clean --force

  


# 删除锁定配置文件

rm -f .bundle/config

  


# 重新安装

bundle install

  


# 如果仍有问题，删除 Gemfile.lock 重新生成

rm -f Gemfile.lock

bundle install

问题4: 缺少 propshaft gem 或其他依赖

原因: 依赖包未完全安装或版本不匹配

解决方案:

# 更新依赖关系

bundle update

  


# 重新安装所有依赖

bundle install

  


# 检查依赖状态

bundle check

问题5: Ruby 版本不匹配

原因: 项目指定的 Ruby 版本与系统版本不符

解决方案:

# 查看项目要求的版本

cat .ruby-version

  


# 方法1: 安装指定版本

rbenv install $(cat .ruby-version)

rbenv local $(cat .ruby-version)

  


# 方法2: 修改为系统版本（推荐）

echo "system" > .ruby-version

问题6: Rails 服务器启动失败

原因: 端口被占用或依赖问题

解决方案:

# 检查端口占用

lsof -i :3000

  


# 使用不同端口启动

rails server -p 3001

  


# 确保所有依赖已安装

bundle check

bundle install

📁 项目结构说明

成功创建的 Rails 项目结构：

blog/

├── app/                 # 应用核心代码

│   ├── controllers/     # 控制器

│   ├── models/         # 模型

│   ├── views/          # 视图

│   └── assets/         # 静态资源

├── config/             # 配置文件

│   ├── database.yml    # 数据库配置

│   ├── routes.rb       # 路由配置

│   └── environments/   # 环境配置

├── db/                 # 数据库相关

├── test/               # 测试文件

├── vendor/             # 第三方代码

│   └── bundle/         # 本地安装的gems

├── Gemfile             # Gem 依赖定义

├── Gemfile.lock        # Gem 版本锁定

├── .ruby-version       # Ruby 版本指定

└── .gitignore          # Git 忽略文件

✅ 环境验证清单

安装完成后，运行以下命令验证环境：

# 1. 检查基础工具

xcode-select -p

brew --version

git --version

  


# 2. 检查 Ruby 环境

rbenv --version  # 或 rvm --version

rbenv version    # 或 rvm current

ruby -v

gem -v

  


# 3. 检查 Rails

rails -v

  


# 4. 检查项目依赖

cd your_project

bundle check

  


# 5. 测试服务器启动

rails server

# 访问 http://localhost:3000

🎯 最佳实践建议

1. 版本管理: 推荐使用 rbenv 而非 RVM，更轻量且稳定

2. Gem 源: 始终配置国内镜像源，显著提升安装速度

3. 本地安装: 使用 bundle config set path 'vendor/bundle' 将 gems 安装到项目本地

4. 版本锁定: 保持 Gemfile.lock 文件，确保团队环境一致

5. 定期更新: 定期运行 bundle update 更新依赖包

6. 备份配置: 备份 .zshrc 等配置文件

📚 参考资源

• Rails 官方文档

• rbenv GitHub

• RVM 官网

• Ruby China Gem 源

• Homebrew 官网

---

总结: 本指南结合了理论安装步骤和实际遇到的问题，提供了完整的 Rails 环境搭建方案。遵循本指南可以避免大部分常见问题，快速搭建稳定的开发环境。 🎉

维护说明: 本指南基于 macOS 系统和 Rails 8.0+ 版本编写，如遇到新问题请及时更新文档。