Githug实战部署完全攻略：从源码到可执行游戏的完整路径

Githug是一款通过55个实战关卡学习Git命令的交互式游戏，本文提供从源码部署到构建可执行gem包的全程指南，帮助开发者快速搭建Git学习环境。通过本指南，你将掌握Ruby项目的依赖管理、gem打包和本地化部署技巧，开启沉浸式Git技能训练。

🔍 环境检测步骤

在部署Githug前需确认系统环境是否满足运行要求，避免因配置问题导致部署失败。

核心依赖检查

执行以下命令验证关键依赖是否安装：

ruby --version  # 检查Ruby版本（需1.8.7+，推荐2.7.1）
git --version   # 确认Git已安装
gem --version   # 验证RubyGems可用性

预期结果：所有命令均能正常输出版本号，无错误提示。

环境兼容性矩阵

操作系统	支持版本	特殊配置要求
Linux	Ubuntu 18.04+	预装build-essential包
macOS	10.14+	需安装Xcode命令行工具
Windows	10/11	建议使用WSL2环境

📥 源码获取与目录结构解析

获取项目源码并了解目录组织，有助于后续部署和自定义修改。

克隆项目仓库

git clone https://gitcode.com/gh_mirrors/gi/githug
cd githug

关键目录说明

├── levels/        # 55个Git练习关卡定义
├── lib/           # 游戏核心逻辑代码
├── spec/          # 单元测试文件
└── githug.gemspec # gem包配置文件

状态检查清单：

• [ ] 已成功克隆仓库
• [ ] 当前目录为项目根目录
• [ ] 能看到上述核心目录结构

📦 依赖管理与安装

Githug使用Bundler管理Ruby依赖，确保所有组件版本兼容。

安装Bundler工具

gem install bundler -v '~> 1.17'  # 安装兼容版本的Bundler

安装项目依赖

bundle install  # 根据Gemfile安装所有依赖

参数说明：

• --without development：跳过开发环境依赖（生产环境使用）
• --path vendor/bundle：将依赖安装到项目本地

🏗️ 构建与安装可执行gem包

将源码打包为Ruby gem，实现系统级别的命令访问。

使用Rake任务构建

rake build  # 执行构建任务，生成gem包

本地安装gem

gem install pkg/githug-*.gem  # 安装生成的gem包

注意事项：

• 如遇权限问题，可添加sudo前缀
• 成功安装后会显示"Successfully installed githug-x.x.x"

✅ 部署验证与游戏启动

确认部署成功并启动Githug开始Git学习之旅。

验证安装状态

githug --version  # 检查版本号
githug --help     # 查看命令帮助

启动游戏

githug  # 启动Githug游戏

首次运行流程：

1. 系统提示创建游戏目录
2. 输入y确认
3. 自动进入第一关教程

🔧 常见问题排查方案

针对部署过程中可能遇到的典型问题，提供系统化解决方案。

问题1：依赖冲突

现象：bundle install时出现版本冲突提示
原因：系统已安装的gem版本与项目要求不兼容
解决步骤：

bundle update  # 更新依赖版本
bundle exec rake build  # 使用bundle环境执行构建

问题2：Git默认分支不兼容

现象：关卡初始化失败，提示"master分支不存在"
原因：新版Git默认分支为main而非master
解决步骤：

git config --global init.defaultBranch master
githug reset  # 重置游戏进度

问题3：gem安装权限不足

现象：gem install时出现"Permission denied"
解决步骤：

sudo gem install pkg/githug-*.gem  # 使用管理员权限安装
# 或使用用户级安装
gem install --user-install pkg/githug-*.gem

🧪 测试套件运行与质量验证

通过执行项目测试确保部署质量和功能完整性。

运行测试套件

bundle exec rspec spec/  # 执行所有测试用例

预期结果：所有测试用例通过（显示"x examples, 0 failures"）

关键测试项说明

• spec/githug/game_spec.rb：游戏核心逻辑测试
• spec/githug/level_spec.rb：关卡系统测试
• spec/githug/repository_spec.rb：Git操作封装测试

🎯 部署成功标志

当满足以下条件时，说明Githug已成功部署：

• ✅ 可通过githug命令启动游戏
• ✅ 能正常显示关卡列表和当前进度
• ✅ 测试套件全部通过
• ✅ 可使用githug hint获取关卡提示
• ✅ 可使用githug reset重置游戏进度

现在，你已拥有一个功能完善的Git学习环境，通过55个实战关卡逐步掌握Git命令的核心用法，从版本控制新手成长为Git高手！