GodotHub 首次启动设置教程:5 分钟配好扫描文件夹,自动发现你的所有 Godot 项目
GodotHub 首次启动设置教程:5 分钟配好扫描文件夹,自动发现你的所有 Godot 项目
GodotHub 是一款集项目管理、引擎版本管理、Git 集成于一体的 Godot 引擎桌面管理工具,它的核心能力是扫描文件夹并自动发现你电脑上的所有 Godot 项目。本文带你走完首次启动的完整设置流程:5 分钟配好扫描文件夹,让项目、引擎版本、模板一次全部到位,以后新建或打开项目再也不用翻文件夹。
GodotHub 是什么?
简单来说,GodotHub 像是 "Unity Hub + GitHub Desktop" 的结合体:
| 模块 | 功能 |
|---|---|
| Projects | 集中管理所有 Godot 项目,支持搜索、标签、分类、拖拽排序 |
| Versions | 浏览、下载、导入已安装的 Godot 引擎版本 |
| Templates | 把项目存成模板,一键创建新项目 |
| Git | 提交、推送、分支管理、差异查看 |
| Asset Store | 直接安装资产库资源到项目 |
首次启动时,GodotHub 会弹出一个引导向导(Onboarding Wizard),引导逻辑在 src/views/OnboardingView.tsx 中实现,共 7 个步骤,全部都可以跳过、随时在设置里改。
一键配好扫描文件夹:引导向导逐步拆解
第 1 步:欢迎页
简单介绍 GodotHub 的功能,点下一步即可。这里还能选择界面语言。
第 2 步(核心):添加项目扫描文件夹
这是最关键的一步:添加你想让 GodotHub 扫描的文件夹,比如 D:\Projects 或 ~/Games。GodotHub 会递归查找其中的 project.godot 文件,凡是包含该文件(或兼容配置文件)的目录都会被识别为一个 Godot 项目。
小技巧:给某个文件夹加星(⭐),它就会成为新建项目对话框中"保存位置"的默认目录。
💡 扫描过程会自动跳过
.git、.godot、.import等无关目录,这些细节写在 src-tauri/src/scan.rs 中。
第 3 步:添加 Godot 版本文件夹
如果你已经手动装过一些 Godot 版本,把可执行文件所在的文件夹添加进来,GodotHub 会自动识别版本号(连 Mono 版本也能区分)。加星的那个文件夹会作为新版本的默认下载位置。
第 4~5 步:模板与分类(可跳过)
- 模板文件夹:里面每个子文件夹都会被导入为项目模板;
- 分类:可以为项目列表预设"进行中 / 原型 / 已完成 / Game Jam"等分组,也可以跳过,稍后在设置里管理。
第 6 步:自定义外观
选择强调色、背景色和圆角大小,应用即时生效。
第 7 步:自动扫描,完成!
点击完成后,GodotHub 会按你配置的文件夹开始扫描项目和引擎版本,并显示 当前 / 总数 的进度条(扫描逻辑见 src/hooks/useOnboarding.ts)。
扫描深度怎么调?找不到项目先看这里
如果扫描后项目没被发现,多半是扫描深度不够。这个参数叫 scan_depth,默认值为 2(定义见 src/hooks/useSettings.ts),含义是:
在每个扫描文件夹内再深入几层子文件夹。数值越小扫描越快、也不会误捡到不相关的项目;如果你的项目嵌套很深,就调大一点。
修改路径:Settings → Storage → Scan depth。
同页面里还有三个常用开关:
| 选项 | 作用 |
|---|---|
| Auto-scan on startup | 每次启动时自动扫描新增的项目和版本 |
| Watch project folders | 文件夹内文件变化时实时发现新项目(秒级延迟) |
| Watch version folders | 自动发现新下载的引擎版本 |
设置完成后能做什么
- 在 Projects 视图搜索、置顶、打标签、用
/快捷指令过滤(如tag:pixel-art、category:Game Jam); - 点项目卡片上的 Open 直接启动对应版本的 Godot 编辑器;
- 向导不是"一次性"的:随时可以在 Settings → Advanced → Run Setup Wizard Again 重新打开,已保存的设置不会丢失。
完整的首次启动说明可参考官方 Wiki:docs/WIKI-GETTING-STARTED.md,所有设置项的详细说明见 docs/WIKI-SETTINGS.md。
常见问题
问:扫描很慢怎么办?
把 scan_depth 调小(默认 2 通常够用),避免把整个磁盘根目录设为扫描文件夹。
问:某个项目没被识别?
确认项目文件夹里有 project.godot,且位于扫描文件夹 scan_depth 层数之内;也可在 Projects 视图手动 Import。
问:想换扫描文件夹? 打开 Settings → Storage,直接增删项目扫描文件夹、版本扫描文件夹和模板目录即可,无需重装。
到这里,你的 GodotHub 已经完全就绪:扫描文件夹配好后,它会持续自动发现项目与引擎版本,5 分钟投入,换来一劳永逸的省心管理。


