文章

Unity插件-版本管理助手开发报告

Unity 内置版本管理助手插件的完整用户帮助手册

发表于
作者 捞鱼
12 分钟阅读
Unity插件-版本管理助手开发报告

插件简介

版本管理助手（Version Control Assistant） 是一款嵌入 Unity 编辑器的 Git 可视化插件。它通过统一窗口管理刷新、暂存、提交、推送、拉取等操作，帮助团队在不离开 Unity 的情况下保持稳定、高效的版本协作。

💡 如果你曾经频繁在 Unity 与命令行之间切换，这款插件就是为了减少这种上下文切换而生。

功能亮点

  1. 一站式控制台：刷新、暂存、提交、推送、拉取集中在单一窗口，减少命令记忆成本。
  2. 树状改动视图：使用颜色编码展示新增/修改/删除/重命名/未跟踪文件，快速洞察工作区状态。
  3. 提交历史时间线：采用时间线卡片展示最近提交，支持作者标签和哈希定位。
  4. 图形化版本回滚：拉取操作支持从远端历史中选择具体提交，再执行 fetch + reset --hard。
  5. 多语言界面：内置中文、英文、日文切换，方便跨区域团队。
  6. 项目级默认配置：在 Project Settings/Version Control Assistant 中预设远端、分支与自定义推送地址。

快速开始

  1. 环境准备
    • 安装 Git，并在终端里确保 git --version 可用。
    • 让 Unity 对项目根目录拥有读写权限。
    • 确认项目已经初始化为 Git 仓库。
  2. 打开插件
    • 在 Unity 顶部菜单中依次点击 Tools → Version Control Assistant。
  3. 首次配置
    • 顶部卡片会自动读取当前分支与远端；若未配置远端，可在右侧提交卡片中手动填写。
  4. 完成首次提交
    • 检查左侧树状改动 → 输入提交说明 → 点击 “提交” → 点击 “推送”。

安装方法

通过 UPM（推荐）

  1. 将插件目录 Packages/com.fire.versioncontrolassistant 纳入项目（Git 子模块或本地包皆可）。
  2. 打开 Window → Package Manager，选择 My Assets 或 In Project，确认插件已被识别。
  3. 若使用 Git 依赖，可在 manifest.json 中加入：
1
2
3
4
5

{
  "dependencies": {
    "com.fire.versioncontrolassistant": "https://github.com/your-org/version-control-assistant.git#1.0.0"
  }
}

⚠️ 通过 Git URL 引入时，请确保远端仓库对团队成员可读。

通过 unitypackage

  1. 在已有项目中右键 Packages/com.fire.versioncontrolassistant → Export Package...。
  2. 将导出的 VersionControlAssistant.unitypackage 发给使用者。
  3. 使用者在目标项目中双击导入；导入后插件会出现在 Tools 菜单下。

详细使用教程

1. 顶部工具栏

  • 刷新：重新执行 git status、更新分支信息与提交历史。
  • 全部暂存：调用 git add -A 暂存所有改动。
  • 拉取：弹出 “选择拉取版本” 对话框，先 fetch 再 reset --hard 至所选提交。
  • 远端/分支输入框：实时编辑推送目标，可引用项目设置中的默认值。
  • 帮助 & 设置：右上角齿轮按钮可切换语言、打开项目设置并访问在线文档。

2. 左侧改动分区

  • 状态总览卡片：展示当前分支、未推送数量与错误提示。
  • 变更树：按照目录分组文件，顶部配有搜索框与统计条。
  • 颜色约定：🟢 新增 / 🔵 修改 / 🔴 删除 / 🟡 重命名 / 🟣 未跟踪。

💡 在树节点上悬停可查看文件完整路径，方便大型项目定位。

3. 右侧提交与推送

  1. 在 “提交说明” 多行文本框中编写描述，建议格式如下：
1
2
3
4

更新：完善版本管理助手的日志视图

- 增加作者标签颜色映射
- 修复提交时间显示错乱的问题
  1. 根据需要选择远端与分支，或勾选 “使用自定义远端地址” 填写完整 Git URL。
  2. 点击 “提交” → 若无报错会自动清空输入框并刷新状态。
  3. 点击 “推送” 将刚才的提交同步到远端。

4. 拉取版本

  1. 点击 “拉取” 打开版本选择器。
  2. 通过搜索框定位到目标提交，支持按作者、哈希或提交信息过滤。
  3. 选中后点击 “拉取所选版本”，插件执行：
    1. git fetch <remote> <branch>
    2. git reset --hard <commit>
  4. 拉取完成后窗口会自动刷新。

⚠️ reset --hard 会清空本地未提交改动，务必提前提交或 git stash。

5. 项目设置

路径：Edit → Project Settings → Version Control Assistant

  • 默认远端 / 默认分支
  • 是否使用自定义推送 URL
  • 打开编辑器时是否自动刷新状态

设置保存后会作为窗口默认值，仍可在窗口中临时覆盖。

常见问题（FAQ）

  1. 插件打开后提示“未找到 Git 仓库”？
    检查项目根目录是否存在 .git 文件夹，若没有请在终端执行 git init，然后点击 “刷新”。

  2. 菜单里找不到版本管理助手？
    确认插件已正确导入；若通过 UPM 安装，请在 Package Manager 中勾选 Enable Preview Packages 并重新导入。

  3. 刷新后变更列表为空？
    可能是所有改动已暂存或提交；执行 git status 核对，或在插件内点击 “全部暂存” 右侧的下拉按钮选择 “撤销暂存”（未来版本计划提供）。

  4. 提交按钮始终灰色？
    需要同时满足：工作区存在变更、提交说明非空。可尝试重新输入提交说明并点击 “刷新”。

  5. 推送失败提示权限不足？
    确认选择了正确的远端与分支，检查 SSH/HTTPS 凭证；必要时在系统凭据管理器中更新。

  6. 拉取后本地修改丢失？
    拉取流程使用 reset --hard，会丢弃未提交内容。建议先提交或执行 git stash 再拉取。

  7. Inspector 不刷新最新状态？
    当插件窗口失去焦点时不会自动更新，重新聚焦窗口后点击 “刷新” 即可。

  8. Unity 版本兼容性如何？
    已在 2021.3、2022.3 LTS 测试；更早的 2020.3 需要手动启用 UI Toolkit 支持。若 UI 渲染异常，请升级到至少 2021 LTS。

  9. Android/iOS 导出会包含插件吗？
    插件位于 Editor 目录，只会在编辑器中编译，不会进入最终构建产物，对移动端包体零影响。

  10. 与其他 Git 插件冲突怎么办？
    如果安装了第三方 Git 工具（如 Plastic SCM 集成），建议仅启用一个，否则可能重复调用 git status 造成性能抖动。

  11. 脚本运行时报错 git executable not found？
    请确保系统 PATH 中可以直接调用 git，Windows 用户可将 Git 安装目录加入环境变量。

  12. 如何只暂存部分文件？
    当前版本仅提供 “全部暂存”。可在终端运行 git add <path> 或在其他 Git GUI 中操作，再回到插件点击 “刷新”。

使用技巧与最佳实践

  • 小步提交：保持一次提交只解决一个问题，便于回滚。
  • 推送前拉取：先拉取远端再推送，降低冲突概率。
  • 善用搜索框：大型项目中通过文件名或路径关键词快速定位改动。
  • 自定义默认值：在项目设置中写死远端与分支，避免误推到错误仓库。
  • 定期查看时间线：快速了解团队成员的最新提交，决定是否需要同步。

💡 推荐在每日开发结束前完成 “刷新 → 查看改动 → 提交 → 推送” 的例行流程。

更新日志

  • v0.2.0（规划中）
    • 支持按文件粒度暂存与撤销暂存
    • 新增冲突检测提醒
    • 提供常见 Git 命令的快捷入口
  • v0.1.0
    • 初始版本发布
    • 支持状态查看、暂存、提交、推送、拉取
    • 内置多语言界面
    • 提供提交历史时间线与远端版本选择器

联系方式与反馈

  • 在线文档：点击插件右上角 “帮助” 按钮或访问 https://lyzbcy.github.io/tags/使用说明/
  • 反馈邮箱：lyzbcy@qq.com
  • 问题模板：提交反馈时请附带 Unity 版本、Git 版本、操作系统以及插件日志（窗口底部日志卡片可复制）

欢迎提出改进建议，让版本管理助手更贴近你的工作流！

Unity开发
技术积累 使用说明
本文由作者按照 CC BY 4.0 进行授权