GFramework

主题

第 1 章：环境准备 ​

在开始使用 GFramework 之前，我们需要配置好开发环境。本章将指导你完成所有必要工具的安装和验证。

系统要求 ​

操作系统 ​

  • Windows：Windows 10 或更高版本（推荐 Windows 11）
  • macOS：macOS 10.15 Catalina 或更高版本
  • Linux：主流发行版（Ubuntu 20.04+, Fedora 35+, Arch Linux 等）

硬件要求 ​

  • CPU：双核或更高（推荐四核）
  • 内存：8 GB RAM（推荐 16 GB）
  • 存储：至少 5 GB 可用空间
  • 显卡：支持 OpenGL 3.3 或更高

安装 .NET SDK ​

GFramework 基于 .NET 6.0+，需要先安装 .NET SDK。

Windows ​

  1. 访问 .NET 官方下载页
  2. 下载 .NET 6.0 SDK 或更高版本
  3. 运行安装程序，按照提示完成安装
  4. 安装完成后，打开命令提示符或 PowerShell

macOS ​

方式一：使用官方安装包

bash
# 访问官网下载 .pkg 安装包
# https://dotnet.microsoft.com/download

方式二：使用 Homebrew

bash
brew install --cask dotnet-sdk

Linux ​

Ubuntu/Debian

bash
# 添加 Microsoft 包仓库
wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

# 安装 .NET SDK
sudo apt-get update
sudo apt-get install -y dotnet-sdk-6.0

Fedora

bash
sudo dnf install dotnet-sdk-6.0

Arch Linux

bash
sudo pacman -S dotnet-sdk

验证 .NET 安装 ​

打开终端或命令提示符，运行：

bash
dotnet --version

你应该看到类似以下输出：

6.0.428

或更高版本（如 7.0.x, 8.0.x）。

提示

建议安装最新的 LTS（长期支持）版本。本教程兼容 .NET 6.0 及以上所有版本。

安装 Godot 引擎 ​

GFramework 的 Godot 集成需要 Godot 4.5.1 或更高版本，并且必须是 .NET 版本（不是标准版）。

下载 Godot ​

  1. 访问 Godot 官方下载页
  2. 选择 Godot 4.5.x - .NET 版本
    • Windows: 下载 Godot_v4.5.x-stable_mono_win64.zip
    • macOS: 下载 Godot_v4.5.x-stable_mono_macos.universal.zip
    • Linux: 下载 Godot_v4.5.x-stable_mono_linux_x86_64.zip

安装 Godot ​

Windows

  1. 解压下载的 ZIP 文件
  2. 将文件夹移动到合适的位置（如 C:\Godot\）
  3. 双击 Godot_v4.5.x-stable_mono_win64.exe 启动

macOS

  1. 解压下载的 ZIP 文件
  2. 将 Godot.app 拖动到 应用程序 文件夹
  3. 首次运行时，右键点击 → 打开（绕过安全检查）

Linux

  1. 解压下载的 ZIP 文件
  2. 添加可执行权限：
bash
chmod +x Godot_v4.5.x-stable_mono_linux.x86_64
  1. 运行：
bash
./Godot_v4.5.x-stable_mono_linux.x86_64

配置 Godot .NET 支持 ​

首次启动 Godot 时，编辑器会自动检测 .NET SDK。

  1. 打开 Godot 编辑器
  2. 点击菜单 编辑器 → 编辑器设置
  3. 在左侧导航中找到 Mono → Builds
  4. 确认 Build Tool 设置为 dotnet CLI

如果 Godot 提示找不到 .NET SDK，确保：

  • .NET SDK 已正确安装
  • 终端中能运行 dotnet --version
  • 重启 Godot 编辑器

注意

必须下载 .NET (Mono) 版本 的 Godot，标准版不支持 C# 开发。文件名中应包含 mono 字样。

安装 IDE（可选但推荐） ​

虽然可以使用任何文本编辑器，但专业的 IDE 能大幅提升开发效率。

Visual Studio 2022（推荐 Windows 用户） ​

  1. 下载 Visual Studio 2022 Community（免费）
  2. 安装时选择以下工作负载：
    • .NET 桌面开发
    • 游戏开发 → 使用 Unity 的游戏开发（可选，提供更好的游戏开发工具）
  3. 确保勾选 .NET 6.0 SDK

JetBrains Rider（推荐跨平台用户） ​

  1. 下载 JetBrains Rider
  2. 安装并激活（提供 30 天试用，或使用社区许可证）
  3. 首次启动时，Rider 会自动检测 .NET SDK

优势：

  • 跨平台支持（Windows, macOS, Linux）
  • 出色的代码补全和重构工具
  • 原生支持 Godot 项目

Visual Studio Code ​

  1. 下载 Visual Studio Code
  2. 安装以下扩展：
    • C# (Microsoft)
    • C# Dev Kit
    • godot-tools

IDE 选择建议

  • Windows 用户：Visual Studio 2022 或 Rider
  • macOS/Linux 用户：Rider 或 VS Code
  • 轻量级需求：VS Code

环境验证 ​

完成所有安装后，让我们创建一个测试项目来验证环境。

1. 创建测试控制台项目 ​

打开终端，运行：

bash
# 创建新的控制台项目
dotnet new console -n GFrameworkTest
cd GFrameworkTest

# 添加 GFramework 核心包
dotnet add package GeWuYou.GFramework.Core

# 编译测试
dotnet build

如果编译成功，说明 .NET 环境配置正确。

2. 创建测试 Godot 项目 ​

  1. 打开 Godot 编辑器
  2. 点击 新建项目
  3. 选择项目路径，命名为 GodotTest
  4. 渲染器 选择 Forward+ 或 Mobile
  5. 点击 创建并编辑

项目创建后，Godot 会提示初始化 C# 项目：

初始化 C# 项目

点击 创建 C# 解决方案，Godot 会自动生成 .csproj 文件。

3. 验证 Godot C# 支持 ​

在 Godot 编辑器中：

  1. 右键点击 文件系统 面板的根目录
  2. 选择 创建新脚本
  3. 语言 选择 C#
  4. 脚本名称输入 TestScript.cs
  5. 点击 创建

如果脚本成功创建并打开外部编辑器，说明 Godot 和 .NET 集成正常。

4. 完整验证脚本 ​

将以下代码粘贴到 TestScript.cs：

csharp
using Godot;
using System;

public partial class TestScript : Node
{
    public override void _Ready()
    {
        GD.Print("✅ Godot + .NET 环境配置成功！");
        GD.Print($"✅ .NET 版本: {Environment.Version}");
        GD.Print("✅ 准备开始使用 GFramework！");
    }
}

在场景中添加一个 Node 节点，附加这个脚本，然后点击 运行场景（F6）。

如果在输出面板看到：

✅ Godot + .NET 环境配置成功！
✅ .NET 版本: 6.0.x
✅ 准备开始使用 GFramework！

恭喜！你的环境已经完全配置好了！

常见问题排查 ​

Godot 找不到 .NET SDK ​

症状：Godot 提示"无法找到 .NET SDK"

解决方案：

  1. 确认终端中能运行 dotnet --version
  2. 重启 Godot 编辑器
  3. 检查 编辑器设置 → Mono → Builds 中的 .NET 路径
  4. 尝试手动指定 .NET SDK 路径

MSBuild 错误 ​

症状：编译时提示 MSBuild 相关错误

解决方案：

bash
# 清理并重新生成项目
dotnet clean
dotnet build

macOS 安全限制 ​

症状：macOS 阻止 Godot 运行

解决方案：

  1. 右键点击 Godot.app
  2. 选择 打开（不是双击）
  3. 在弹出的对话框中点击 打开
  4. 后续可以正常双击启动

Linux 缺少依赖 ​

症状：Linux 下 Godot 无法启动

解决方案：

bash
# Ubuntu/Debian
sudo apt-get install libxcursor1 libxinerama1 libxi6 libxrandr2 libgl1

# Fedora
sudo dnf install libXcursor libXinerama libXi libXrandr mesa-libGL

下一步 ​

环境配置完成！现在你已经准备好开始使用 GFramework 了。

在下一章中，我们将：

  • 创建一个新的 Godot 项目
  • 引入 GFramework NuGet 包
  • 搭建基础的项目架构
  • 创建游戏入口点

👉 第 2 章：项目创建与初始化

本章检查清单
  • [ ] .NET SDK 已安装并可以运行 dotnet --version
  • [ ] Godot 4.5.1+ .NET 版本已安装
  • [ ] IDE 已安装（Visual Studio / Rider / VS Code）
  • [ ] 测试项目成功编译
  • [ ] Godot 能够创建和运行 C# 脚本

基于 Apache 2.0 许可证发布

Copyright © 2026 GeWuYou