Grasscutter 服务端搭建与构建实战指南功能清单、快速启动与 Gradle 编译全解析【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter本篇技术指南以仓库官方日文文档 docs/README_ja-JP.md 为主体结合仓库源码主程序入口、启动参数解析、Gradle 构建脚本、Windows 启动脚本与手册前端工程进行深度扩充系统讲解 Grasscutter 服务端的当前功能范围、一键快速启动Cultivation 方案、从源码 Gradle 构建、手册生成与故障排查完整流程。读完本文你将掌握从零搭建一套可登录、可战斗、可抽卡的 Grasscutter 私服环境的完整实战能力并理解服务端启动背后各模块的真实分工。一、项目定位与当前已实现功能Grasscutter 是对某款动漫风格游戏的服务端重实现reimplementation使用 Java 编写采用 Gradle 进行依赖管理与构建。根据 docs/README_ja-JP.md 的官方声明目前已经实现的核心功能包括功能说明对应源码模块佐证登录ログイン账户认证与会话建立src/main/java/emu/grasscutter/auth战斗戦闘战斗逻辑与伤害结算src/main/java/emu/grasscutter/game/entity好友列表フレンドリスト好友关系管理src/main/java/emu/grasscutter/game/friends传送テレポート场景切换与坐标传送src/main/java/emu/grasscutter/game/world祈愿/抽卡ガチャ卡池与抽卡记录src/main/java/emu/grasscutter/game/gacha多人联机マルチプレイ部分可用src/main/java/emu/grasscutter/game/systems/MultiplayerSystem.java控制台刷怪通过服务端控制台指令生成怪物src/main/java/emu/grasscutter/command/commands/SpawnCommand.java背包功能领取/升级物品与角色等src/main/java/emu/grasscutter/game/inventory需要特别强调的是版本兼容性约束根据仓库根目录 README.md 中的说明Grasscutter 目前截至 2025 年 1 月 12 日仅支持至 REL4.0.1枫丹版本的游戏客户端且游戏版本与服务端版本必须严格匹配不能混用。日文文档也明确要求准备 REL4.0.X 版本的客户端。搭建前务必先确认手头客户端的版本号再选用对应版本的 Grasscutter 服务端。二、快速启动パパっとスタートアップ基于 Cultivation 的一键方案对于希望跳过编译、直接体验服务的用户官方推荐使用 Cultivation 图形化工具完成自动化部署。日文文档给出的完整流程如下准备 Java 17安装 Java 17 及以上版本 中sourceCompatibility JavaVersion.VERSION_17准备 MongoDB安装 MongoDB Community Server服务端数据持久化依赖 MongoDB启动入口中会调用DatabaseManager.initialize()见 src/main/java/emu/grasscutter/Grasscutter.java准备游戏客户端版本必须为 REL4.0.X下载 Cultivation最新版本使用.msi安装包安装以管理员权限运行 Cultivation点击右上角的下载图标按钮点击Download All-in-One一键下载整合包点击右上角的齿轮图标进入设置在Game Install Path中指定游戏文件所在路径在Custom Java Path中指定 Java 可执行文件路径示例C:\Program Files\Java\jdk-17\bin\java.exe其余设置保持默认不要改动点击 Launch 按钮旁边的小按钮用于启动资源/代理相关组件点击Launch按钮启动服务端在游戏内输入任意用户名登录。若登录相关配置为默认值密码可随意填写默认认证逻辑由 src/main/java/emu/grasscutter/auth/DefaultAuthentication.java 实现。这套流程把 Java、MongoDB、代理转发、游戏资源加载等环节全部封装进 Cultivation是新手最快的上手路径。三、从源码构建ビルド如果需要自行编译最新代码、参与二次开发或验证构建流程则使用 Gradle 完成构建。仓库根目录已内置 Gradle Wrappergradlew、gradlew.bat、gradle/wrapper无需手动安装 Gradle。3.1 环境需求依赖版本用途必需性Java SE Development Kit17 或更高编译与运行服务端必需Git任意较新版本拉取仓库与子模块必需NodeJS任意较新版本编译 Web 端手册handbook可选仅构建手册时需要3.2 Clone 仓库git clone --recurse-submodules https://github.com/Grasscutters/Grasscutter.git cd Grasscutter注意--recurse-submodules会一并拉取子模块是完整构建的前提。3.3 编译Windowsgit clone https://github.com/Grasscutters/Grasscutter.git cd Grasscutter .\gradlew.bat # 构建编译环境 .\gradlew jar # 编译打包Linuxgit clone https://github.com/Grasscutters/Grasscutter.git cd Grasscutter chmod x gradlew ./gradlew jar # 编译打包关于手册生成失败的规避日文文档特别提示在某些环境下手册handbook即内置的 GM 查询工具前端的生成可能失败。此时可在gradlew jar命令后追加-PskipHandbook1跳过手册构建./gradlew jar -PskipHandbook13.4 构建配置源码级解读从 build.gradle 可以看到本次仓库快照的工程化细节版本号version 1.7.4group io.grasscutterJava 版本sourceCompatibility/targetCompatibility均锁定为JavaVersion.VERSION_17关键插件com.google.protobuf版本 0.8.18用于自动生成网络协议代码产物可见于 src/generated/main/java/emu/grasscutter/net/proto、com.diffplug.spotless代码格式检查、io.freefair.lombokLombok 注解处理核心依赖Netty网络通信、protobuf-java协议序列化、MorphiaMongoDB 对象映射、quartz定时任务、luajLua 脚本引擎供场景脚本 src/main/java/emu/grasscutter/scripts 使用、jline控制台交互本地 JARimplementation fileTree(dir: lib, include: [*.jar])即 lib 目录下的bcrypt-0.8.0.jar、bytes-1.3.0.jar、kcp-1.5.1.jar等会被直接打入依赖。编译产出的grasscutter.jar位于项目根目录日文文档明确说明 生成されたjarファイルはプロジェクトのルートフォルダにあります。四、手动生成手册Handbook手册是服务端内置的查询工具Web 前端用于在游戏内/网页端查看物品、角色、场景等数据。日文文档给出了两种手动构建方式。方式一通过 Gradle./gradlew generateHandbook方式二通过 NPM直接操作前端工程cd src/handbook npm install npm run build手册前端工程位于 src/handbook从 src/handbook/package.json 可以看出其技术栈React 18 TypeScript Vite 4 Tailwind CSS Sass并借助vite-plugin-singlefile将产物打包为单文件方便服务端内嵌托管postinstall阶段还会执行patch-package应用补丁见 src/handbook/patches 下的react-virtualized9.22.3.patch。服务端启动时也会在资源加载阶段自动生成手册Tools.createGmHandbooks(false)见 Grasscutter.java手动构建主要服务于定制与离线场景。五、启动运行与配置详解5.1 主入口与运行模式服务端主类为 src/main/java/emu/grasscutter/Grasscutter.javamain方法依次完成加载密钥Crypto.loadKeys()→ 解析启动参数 → 创建命令映射 → 初始化数据库MongoDB→ 初始化认证与权限系统 → 按运行模式创建 GameServer / HttpServerDispatch→ 加载资源 → 启动服务器 → 打开控制台。Grasscutter 支持三种运行模式运行模式行为判定条件HYBRID同时启动游戏服务器与 HTTP/Dispatch 服务器默认无覆盖参数时GAME_ONLY仅启动游戏服务器启动参数-gameDISPATCH_ONLY仅启动 Dispatch 服务器SDK 查询/调度启动参数-dispatch5.2 启动参数命令行选项启动参数解析逻辑见 src/main/java/emu/grasscutter/utils/StartupArguments.java常用参数整理如下参数作用示例-version/-v打印版本信息后退出java -jar grasscutter.jar -version-lang代码指定首选语言覆盖配置-langja-game仅运行游戏服务器java -jar grasscutter.jar -game-dispatch仅运行 Dispatch 服务器java -jar grasscutter.jar -dispatch-debug开启调试日志主日志器切到 DEBUGjava -jar grasscutter.jar -debug-debugall开启全量调试含第三方服务日志java -jar grasscutter.jar -debugall-noconsole不启动交互控制台java -jar grasscutter.jar -noconsole-test测试模式禁用控制台与 HTTP 加密java -jar grasscutter.jar -test-dump内容,语言导出指定数据commands/avatars/items/scenes/entities/quests/areas-dumpitems,ja-dumppacketids导出协议包 ID 映射java -jar grasscutter.jar -dumppacketids5.3 配置文件 config.json服务端首次启动时会自动生成根目录下的config.jsonconfigFile new File(./config.json)。配置结构由 src/main/java/emu/grasscutter/config/ConfigContainer.java 定义并通过 src/main/java/emu/grasscutter/config/Configuration.java 暴露为静态常量供全工程引用核心区块包括language服务端语言对应日文文档所服务的ja语言环境serverHTTP/Dispatch/Game 服务器监听地址与端口、游戏选项背包上限、手册开关等、调试模式、加密与策略配置databaseInfoMongoDB 连接信息URI、数据库名account账户体系相关配置默认认证下密码可任意填写folderStructure数据、插件、脚本、协议包等资源目录。5.4 Windows 一键启动脚本仓库提供了 start.cmd 与配套的 start_config.cmd 两个 Windows 批处理脚本start_config.cmd为可编辑的配置文件通过set指定各组件可执行文件路径JAVA_PATHJava 目录、MITMDUMP_PATHmitmproxy 目录、MONGODB_PATHMongoDB 目录、SERVER_JAR_NAMEgrasscutter.jar、PROXY_SCRIPT_NAMEproxy等若希望从系统 PATH 直接调用而无需检测文件存在可将路径填为DO_NOT_CHECK_PATHstart.cmd会依次读取start_config.cmd→ 检测 Java/jar → 以管理员权限启动 mitmproxy 代理配合 scripts/proxy.py→ 自动将 mitmproxy 的 CA 证书安装进系统根证书库 → 写入系统代理127.0.0.1:8080→ 后台启动mongod.exe数据目录为resources\Database→ 以java -jar grasscutter.jar启动服务端退出时自动恢复原代理设置、卸载 CA 证书并关闭 mongod/mitmdump 进程。5.5 容器化运行仓库根目录提供 Dockerfile 与 entrypoint.sh容器启动命令即为java -jar /app/grasscutter.jar适合在 Linux 服务器上一键部署。六、辅助脚本与工具scripts 目录还提供了若干开发辅助脚本scripts/install/install.sh 与install_without_dependencies.sh自动化安装依赖scripts/gradlew-jar.batWindows 下便捷执行gradlew jar的封装scripts/proxy.py 与proxy_config.pymitmproxy 代理脚本用于拦截/转发游戏流量对应start.cmd中的代理环节scripts/manage_languages.py多语言翻译文件管理工具仓库根目录 docs 下即有多语言 README日文版正是其中之一。七、故障排查トラブルシューティング日文文档给出的排查路径如下构建阶段手册生成失败这是最常见的问题之一。解决办法是在gradlew jar后追加-PskipHandbook1跳过手册生成服务端在运行时仍会尝试自动生成Tools.createGmHandbooks(false)版本不匹配游戏客户端与服务端版本必须一致服务端当前支持至 REL4.0.X混用会导致登录或资源加载异常启动依赖缺失确认 Java 17、MongoDB 均已正确安装且可被服务端访问需要更复杂的排查加入官方 Discord 服务器进入支持频道查看其他用户遇到过的常见问题汇总或直接向社区求助官方文档明确推荐该途径且仓库对超出最新 release 的版本不提供手把手指导务必使用与客户端匹配的正式版本。八、总结本文围绕官方日文文档 docs/README_ja-JP.md 完整还原了 Grasscutter 的部署与构建全流程从功能清单出发走通快速启动Cultivation→ 源码编译Gradle→ 手册生成 → 启动运行 → 故障排查的完整链路并结合 Grasscutter.java、StartupArguments.java、build.gradle、start.cmd 等源码与脚本将文档中的每一步落到了具体的实现依据上。无论是想一键体验服务端还是准备自行编译参与二次开发本文给出的命令、参数与配置说明均可直接作为操作手册使用。【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Grasscutter 服务端搭建与构建实战指南：功能清单、快速启动与 Gradle 编译全解析
Grasscutter 服务端搭建与构建实战指南功能清单、快速启动与 Gradle 编译全解析【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter本篇技术指南以仓库官方日文文档 docs/README_ja-JP.md 为主体结合仓库源码主程序入口、启动参数解析、Gradle 构建脚本、Windows 启动脚本与手册前端工程进行深度扩充系统讲解 Grasscutter 服务端的当前功能范围、一键快速启动Cultivation 方案、从源码 Gradle 构建、手册生成与故障排查完整流程。读完本文你将掌握从零搭建一套可登录、可战斗、可抽卡的 Grasscutter 私服环境的完整实战能力并理解服务端启动背后各模块的真实分工。一、项目定位与当前已实现功能Grasscutter 是对某款动漫风格游戏的服务端重实现reimplementation使用 Java 编写采用 Gradle 进行依赖管理与构建。根据 docs/README_ja-JP.md 的官方声明目前已经实现的核心功能包括功能说明对应源码模块佐证登录ログイン账户认证与会话建立src/main/java/emu/grasscutter/auth战斗戦闘战斗逻辑与伤害结算src/main/java/emu/grasscutter/game/entity好友列表フレンドリスト好友关系管理src/main/java/emu/grasscutter/game/friends传送テレポート场景切换与坐标传送src/main/java/emu/grasscutter/game/world祈愿/抽卡ガチャ卡池与抽卡记录src/main/java/emu/grasscutter/game/gacha多人联机マルチプレイ部分可用src/main/java/emu/grasscutter/game/systems/MultiplayerSystem.java控制台刷怪通过服务端控制台指令生成怪物src/main/java/emu/grasscutter/command/commands/SpawnCommand.java背包功能领取/升级物品与角色等src/main/java/emu/grasscutter/game/inventory需要特别强调的是版本兼容性约束根据仓库根目录 README.md 中的说明Grasscutter 目前截至 2025 年 1 月 12 日仅支持至 REL4.0.1枫丹版本的游戏客户端且游戏版本与服务端版本必须严格匹配不能混用。日文文档也明确要求准备 REL4.0.X 版本的客户端。搭建前务必先确认手头客户端的版本号再选用对应版本的 Grasscutter 服务端。二、快速启动パパっとスタートアップ基于 Cultivation 的一键方案对于希望跳过编译、直接体验服务的用户官方推荐使用 Cultivation 图形化工具完成自动化部署。日文文档给出的完整流程如下准备 Java 17安装 Java 17 及以上版本 中sourceCompatibility JavaVersion.VERSION_17准备 MongoDB安装 MongoDB Community Server服务端数据持久化依赖 MongoDB启动入口中会调用DatabaseManager.initialize()见 src/main/java/emu/grasscutter/Grasscutter.java准备游戏客户端版本必须为 REL4.0.X下载 Cultivation最新版本使用.msi安装包安装以管理员权限运行 Cultivation点击右上角的下载图标按钮点击Download All-in-One一键下载整合包点击右上角的齿轮图标进入设置在Game Install Path中指定游戏文件所在路径在Custom Java Path中指定 Java 可执行文件路径示例C:\Program Files\Java\jdk-17\bin\java.exe其余设置保持默认不要改动点击 Launch 按钮旁边的小按钮用于启动资源/代理相关组件点击Launch按钮启动服务端在游戏内输入任意用户名登录。若登录相关配置为默认值密码可随意填写默认认证逻辑由 src/main/java/emu/grasscutter/auth/DefaultAuthentication.java 实现。这套流程把 Java、MongoDB、代理转发、游戏资源加载等环节全部封装进 Cultivation是新手最快的上手路径。三、从源码构建ビルド如果需要自行编译最新代码、参与二次开发或验证构建流程则使用 Gradle 完成构建。仓库根目录已内置 Gradle Wrappergradlew、gradlew.bat、gradle/wrapper无需手动安装 Gradle。3.1 环境需求依赖版本用途必需性Java SE Development Kit17 或更高编译与运行服务端必需Git任意较新版本拉取仓库与子模块必需NodeJS任意较新版本编译 Web 端手册handbook可选仅构建手册时需要3.2 Clone 仓库git clone --recurse-submodules https://github.com/Grasscutters/Grasscutter.git cd Grasscutter注意--recurse-submodules会一并拉取子模块是完整构建的前提。3.3 编译Windowsgit clone https://github.com/Grasscutters/Grasscutter.git cd Grasscutter .\gradlew.bat # 构建编译环境 .\gradlew jar # 编译打包Linuxgit clone https://github.com/Grasscutters/Grasscutter.git cd Grasscutter chmod x gradlew ./gradlew jar # 编译打包关于手册生成失败的规避日文文档特别提示在某些环境下手册handbook即内置的 GM 查询工具前端的生成可能失败。此时可在gradlew jar命令后追加-PskipHandbook1跳过手册构建./gradlew jar -PskipHandbook13.4 构建配置源码级解读从 build.gradle 可以看到本次仓库快照的工程化细节版本号version 1.7.4group io.grasscutterJava 版本sourceCompatibility/targetCompatibility均锁定为JavaVersion.VERSION_17关键插件com.google.protobuf版本 0.8.18用于自动生成网络协议代码产物可见于 src/generated/main/java/emu/grasscutter/net/proto、com.diffplug.spotless代码格式检查、io.freefair.lombokLombok 注解处理核心依赖Netty网络通信、protobuf-java协议序列化、MorphiaMongoDB 对象映射、quartz定时任务、luajLua 脚本引擎供场景脚本 src/main/java/emu/grasscutter/scripts 使用、jline控制台交互本地 JARimplementation fileTree(dir: lib, include: [*.jar])即 lib 目录下的bcrypt-0.8.0.jar、bytes-1.3.0.jar、kcp-1.5.1.jar等会被直接打入依赖。编译产出的grasscutter.jar位于项目根目录日文文档明确说明 生成されたjarファイルはプロジェクトのルートフォルダにあります。四、手动生成手册Handbook手册是服务端内置的查询工具Web 前端用于在游戏内/网页端查看物品、角色、场景等数据。日文文档给出了两种手动构建方式。方式一通过 Gradle./gradlew generateHandbook方式二通过 NPM直接操作前端工程cd src/handbook npm install npm run build手册前端工程位于 src/handbook从 src/handbook/package.json 可以看出其技术栈React 18 TypeScript Vite 4 Tailwind CSS Sass并借助vite-plugin-singlefile将产物打包为单文件方便服务端内嵌托管postinstall阶段还会执行patch-package应用补丁见 src/handbook/patches 下的react-virtualized9.22.3.patch。服务端启动时也会在资源加载阶段自动生成手册Tools.createGmHandbooks(false)见 Grasscutter.java手动构建主要服务于定制与离线场景。五、启动运行与配置详解5.1 主入口与运行模式服务端主类为 src/main/java/emu/grasscutter/Grasscutter.javamain方法依次完成加载密钥Crypto.loadKeys()→ 解析启动参数 → 创建命令映射 → 初始化数据库MongoDB→ 初始化认证与权限系统 → 按运行模式创建 GameServer / HttpServerDispatch→ 加载资源 → 启动服务器 → 打开控制台。Grasscutter 支持三种运行模式运行模式行为判定条件HYBRID同时启动游戏服务器与 HTTP/Dispatch 服务器默认无覆盖参数时GAME_ONLY仅启动游戏服务器启动参数-gameDISPATCH_ONLY仅启动 Dispatch 服务器SDK 查询/调度启动参数-dispatch5.2 启动参数命令行选项启动参数解析逻辑见 src/main/java/emu/grasscutter/utils/StartupArguments.java常用参数整理如下参数作用示例-version/-v打印版本信息后退出java -jar grasscutter.jar -version-lang代码指定首选语言覆盖配置-langja-game仅运行游戏服务器java -jar grasscutter.jar -game-dispatch仅运行 Dispatch 服务器java -jar grasscutter.jar -dispatch-debug开启调试日志主日志器切到 DEBUGjava -jar grasscutter.jar -debug-debugall开启全量调试含第三方服务日志java -jar grasscutter.jar -debugall-noconsole不启动交互控制台java -jar grasscutter.jar -noconsole-test测试模式禁用控制台与 HTTP 加密java -jar grasscutter.jar -test-dump内容,语言导出指定数据commands/avatars/items/scenes/entities/quests/areas-dumpitems,ja-dumppacketids导出协议包 ID 映射java -jar grasscutter.jar -dumppacketids5.3 配置文件 config.json服务端首次启动时会自动生成根目录下的config.jsonconfigFile new File(./config.json)。配置结构由 src/main/java/emu/grasscutter/config/ConfigContainer.java 定义并通过 src/main/java/emu/grasscutter/config/Configuration.java 暴露为静态常量供全工程引用核心区块包括language服务端语言对应日文文档所服务的ja语言环境serverHTTP/Dispatch/Game 服务器监听地址与端口、游戏选项背包上限、手册开关等、调试模式、加密与策略配置databaseInfoMongoDB 连接信息URI、数据库名account账户体系相关配置默认认证下密码可任意填写folderStructure数据、插件、脚本、协议包等资源目录。5.4 Windows 一键启动脚本仓库提供了 start.cmd 与配套的 start_config.cmd 两个 Windows 批处理脚本start_config.cmd为可编辑的配置文件通过set指定各组件可执行文件路径JAVA_PATHJava 目录、MITMDUMP_PATHmitmproxy 目录、MONGODB_PATHMongoDB 目录、SERVER_JAR_NAMEgrasscutter.jar、PROXY_SCRIPT_NAMEproxy等若希望从系统 PATH 直接调用而无需检测文件存在可将路径填为DO_NOT_CHECK_PATHstart.cmd会依次读取start_config.cmd→ 检测 Java/jar → 以管理员权限启动 mitmproxy 代理配合 scripts/proxy.py→ 自动将 mitmproxy 的 CA 证书安装进系统根证书库 → 写入系统代理127.0.0.1:8080→ 后台启动mongod.exe数据目录为resources\Database→ 以java -jar grasscutter.jar启动服务端退出时自动恢复原代理设置、卸载 CA 证书并关闭 mongod/mitmdump 进程。5.5 容器化运行仓库根目录提供 Dockerfile 与 entrypoint.sh容器启动命令即为java -jar /app/grasscutter.jar适合在 Linux 服务器上一键部署。六、辅助脚本与工具scripts 目录还提供了若干开发辅助脚本scripts/install/install.sh 与install_without_dependencies.sh自动化安装依赖scripts/gradlew-jar.batWindows 下便捷执行gradlew jar的封装scripts/proxy.py 与proxy_config.pymitmproxy 代理脚本用于拦截/转发游戏流量对应start.cmd中的代理环节scripts/manage_languages.py多语言翻译文件管理工具仓库根目录 docs 下即有多语言 README日文版正是其中之一。七、故障排查トラブルシューティング日文文档给出的排查路径如下构建阶段手册生成失败这是最常见的问题之一。解决办法是在gradlew jar后追加-PskipHandbook1跳过手册生成服务端在运行时仍会尝试自动生成Tools.createGmHandbooks(false)版本不匹配游戏客户端与服务端版本必须一致服务端当前支持至 REL4.0.X混用会导致登录或资源加载异常启动依赖缺失确认 Java 17、MongoDB 均已正确安装且可被服务端访问需要更复杂的排查加入官方 Discord 服务器进入支持频道查看其他用户遇到过的常见问题汇总或直接向社区求助官方文档明确推荐该途径且仓库对超出最新 release 的版本不提供手把手指导务必使用与客户端匹配的正式版本。八、总结本文围绕官方日文文档 docs/README_ja-JP.md 完整还原了 Grasscutter 的部署与构建全流程从功能清单出发走通快速启动Cultivation→ 源码编译Gradle→ 手册生成 → 启动运行 → 故障排查的完整链路并结合 Grasscutter.java、StartupArguments.java、build.gradle、start.cmd 等源码与脚本将文档中的每一步落到了具体的实现依据上。无论是想一键体验服务端还是准备自行编译参与二次开发本文给出的命令、参数与配置说明均可直接作为操作手册使用。【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考