★ FEATURED ARTICLE 1. 从 Mine Goose Duck 0.1 说起Forge 1.19.2 模组开发环境到底怎么搭Mine Goose Duck 0.1 发布之后很多想自己动手改模组、加身份物品的朋友来问我这个基于 Forge 1.19.2 的模组本地开发环境到底怎么从零跑起来我这次就把整套流程拆开讲清楚——从 JDK 选择、Forge MDK 导入、Gradle 依赖拉取到把模组里调用大模型能力的部分接到 TaoToken 的统一 Key/API 通道上最后验证模组能正常加载、身份物品能注册进游戏。先说清楚这套东西是什么、能做什么、适合谁。Forge 1.19.2 是 Minecraft 1.19.2 版本对应的模组加载器Mine Goose Duck 就是跑在它上面的一个「鹅鸭杀」玩法模组里面注册了警长、正义使者、星界行者、保镖、观鸟者、鹈鹕、秃鹫、鸽子、爆炸王、隐形、专业杀手这些身份物品还加了鹅、鸭、木乃伊三种新生物和扭蛋机。你要做的是让这套代码在你自己的机器上编译通过、进游戏能看到生物和身份物品同时把模组里需要联网的 AI 对话/文本生成能力统一走 TaoToken 的 API 通道而不是每个功能各配一套 Key。适合谁看有 Java 基础、想入门 Forge 模组开发的人已经能跑原版模组、但卡在依赖下载或 API 配置的人以及想把模组里的 AI 能力集中管理、不想在代码里散落一堆密钥的开发者。整篇按「先搭环境、再配通道、然后验证、最后排错」的顺序走每一步都给可复制的命令和配置。我试过在 Windows 和 macOS 上各跑一遍坑主要集中在 Gradle 拉依赖和 JDK 版本上下面会逐个说。你跟着做大概 30 到 40 分钟能跑通本地链路。2. TaoToken 前置准备统一 Key 与 API 通道是什么在动 Forge 之前先把 TaoToken 这一侧准备好不然后面模组里调用 AI 能力时会来回改配置。TaoToken 在这里扮演的角色是一个统一的模型调用入口你申请一个 Key通过一个 Base URL 就能访问多种模型不用为每个模型单独记地址和密钥。对模组开发来说好处是代码里只维护一份配置换模型只改 Model ID。你需要准备三样东西我把它叫做「三件套」Base URL、API Key、Model ID。这三件套在后面 Forge 项目的配置文件、以及 Claude Code / Cline 这类工具里都会反复出现先记牢。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数直接作为请求前缀。API Key 去控制台生成路径是 API Keys 页面生成后只显示一次复制存好。Model ID 按你要用的模型填比如做文本对话就填对应的对话模型标识做代码补全就填代码模型标识。具体操作顺序先打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力然后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 Key生成后到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理。如果你只是想先验证模型能不能通可以直接用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条消息试试确认 Key 有效再往下走。这里有个容易忽略的点Key 的权限和作用范围。生成 Key 时看清楚它绑定的额度和可用模型范围别生成一个只能调某个模型的 Key结果模组里想换模型发现调不通。另外 Key 不要硬编码进会提交到 Git 的源码里后面我会给一个用本地配置文件隔离的做法。如果你打算长期做模组开发、还要接 Agent 类工具可以顺带看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它更适合持续编码场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite遇到参数不确定时以文档为准。3. 可复制配置Forge MDK 与 TaoToken 接入片段这一节是核心给的都是能直接复制粘贴的片段。先搭 Forge 1.19.2 的 MDK再把 TaoToken 的配置接进去。第一步确认 JDK。Forge 1.19.2 需要 JDK 17别用 JDK 8 或 21否则 Gradle 构建会报不支持的 class 版本。命令行验证java -version输出里要能看到17.0.x。如果不是 17先装一个 JDK 17 并切换JAVA_HOME。第二步拿 Forge 1.19.2 的 MDK。去 Forge 官方文件页选 1.19.2 对应的 MDK 压缩包解压到一个空目录比如mine-goose-duck-dev。解压后目录里应该有build.gradle、gradle.properties、settings.gradle、src等。第三步改gradle.properties把模组元信息填上。这是 Forge MDK 的标准配置路径就是项目根目录的gradle.propertiesorg.gradle.jvmargs-Xmx3G org.gradle.daemonfalse minecraft_version1.19.2 forge_version43.2.0 mod_idminegooseduck mod_nameMine Goose Duck mod_licenseMIT mod_version0.1.0 mod_group_idcom.example.minegooseduck mod_authorsyourname mod_descriptionMine Goose Duck mod for Forge 1.19.2forge_version按你下载的 MDK 实际版本填43.x 系列对应 1.19.2。mod_id全小写别用大写或空格。第四步把 TaoToken 三件套写进一个本地配置不要写进gradle.properties那个会进版本库。在项目根目录建一个taotoken.local.properties并把它加进.gitignoretaotoken.base_urlhttps://taotoken.net/api taotoken.api_keysk-你的Key taotoken.model_id你的模型ID然后在build.gradle里读取这个文件把值注入到模组运行时能读到的资源里。在build.gradle末尾加一段def localProps new Properties() def localFile file(taotoken.local.properties) if (localFile.exists()) { localFile.withInputStream { localProps.load(it) } } processResources { inputs.property taotoken_base_url, localProps.getProperty(taotoken.base_url, ) inputs.property taotoken_model_id, localProps.getProperty(taotoken.model_id, ) filesMatching(taotoken.properties) { expand( base_url: localProps.getProperty(taotoken.base_url, ), model_id: localProps.getProperty(taotoken.model_id, ) ) } }注意 API Key 不要通过processResources打进 jar那等于把密钥发出去。Key 只在本地开发时由运行参数注入下面给做法。第五步在src/main/resources下建taotoken.properties模板taotoken.base_url${base_url} taotoken.model_id${model_id}第六步本地运行时把 Key 通过 JVM 参数传进去。在 IDE 的 Run Configuration 里给 VM options 加-Dtaotoken.api_keysk-你的Key代码里用System.getProperty(taotoken.api_key)读取。这样 Key 不进 jar、不进 Git只在本地运行环境里存在。第七步写一个最小的调用示例验证通道能通。在模组主类里加一个方法public static String askTaoToken(String prompt) throws IOException { String baseUrl System.getProperty(taotoken.base_url, https://taotoken.net/api); String apiKey System.getProperty(taotoken.api_key, ); String modelId System.getProperty(taotoken.model_id, ); HttpClient client HttpClient.newHttpClient(); String body {\model\:\ modelId \,\messages\:[{\role\:\user\,\content\:\ prompt \}]}; HttpRequest request HttpRequest.newBuilder() .uri(URI.create(baseUrl /v1/chat/completions)) .header(Content-Type, application/json) .header(Authorization, Bearer apiKey) .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); }这段是示意实际请求体按你用的模型接口格式调整参数以接入文档为准。重点是三件套的读取方式和请求头Authorization: Bearer的写法。到这里Forge MDK 和 TaoToken 配置就都齐了。下一步是构建和验证。4. 验证请求与模组加载从 gradle runClient 到身份物品注册配置写完先别急着写业务逻辑把「能构建、能进游戏、能调通 API」这三件事验证掉。先构建。在项目根目录执行./gradlew buildWindows 下用gradlew.bat build。第一次会拉 Forge 和依赖时间比较长耐心等。如果卡在下载看第五节排错。构建成功后build/libs下会生成 jar。再跑客户端./gradlew runClient这会启动一个带 Forge 的 Minecraft 1.19.2 客户端。进游戏后新建世界检查两件事一是新生物鹅、鸭、木乃伊能不能刷出来可以用/summon命令测试实体 ID 按你注册的填二是身份物品能不能通过创造模式物品栏或扭蛋机拿到。如果这两样都在说明模组加载和注册没问题。然后验证 TaoToken 通道。在模组里加一个调试命令或者直接在游戏里触发一次askTaoToken调用把返回打到日志。命令行侧也可以先用 curl 单独验证 Key 和地址curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d {model:你的模型ID,messages:[{role:user,content:ping}]}返回里有正常的choices数组就说明三件套没问题。这一步能帮你把「是 Key 的问题」和「是模组代码的问题」分开。成功结果长这样gradlew build输出BUILD SUCCESSFULrunClient进游戏后能看到鹅、鸭、木乃伊curl 返回 JSON 里choices[0].message.content有内容。三个都过本地开发链路就算跑通了。如果你用的是 Claude Code 这类工具辅助写模组代码接入时同样填三件套Base URL 填https://taotoken.net/apiKey 填你生成的Model ID 填对应模型。Claude Code 的接入说明在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite按文档把地址和 Key 配好即可不要用其它来路不明的地址。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来遇到对号入座。401 Unauthorized。最常见。原因通常是 Key 没传对或没生效。检查三处Authorization头是不是Bearer sk-xxx格式中间有空格Key 是不是复制时带了换行或空格Key 是不是已经过期或被禁用。用 curl 单独测一次能排除模组代码干扰。如果 curl 也 401就是 Key 本身的问题去 API Keys 页面重新生成。local proxy failed / connection refused。这个报错一般出现在你本地配了某个代理端口但代理没起来或者地址写错。先确认你请求的 Base URL 是https://taotoken.net/api不要自己拼奇怪的端口。如果你本地环境有网络工具在跑先关掉再试避免请求被劫持到不存在的本地端口。模组里如果用了自定义 HttpClient 并设了 Proxy检查ProxySelector配置。reading choices 报错 / 解析不到 choices。这通常是返回体不是预期的 JSON或者你解析的字段路径不对。先看原始返回字符串别直接反序列化。可能情况返回的是错误信息比如额度不足、模型 ID 不存在此时没有choices字段或者模型 ID 填错接口返回了错误对象。把model_id和文档里的可用模型列表对一遍。还有一种是把流式返回当非流式解析导致 JSON 不完整。OAuth 相关报错。如果你在 Claude Code 或类似工具里看到 OAuth 报错多半是认证方式选错了。用 API Key 方式接入时不需要走 OAuth 流程直接在配置里填 Base URL 和 Key。检查工具配置里是不是残留了旧的 OAuth 配置清掉再填三件套。Codex 的auth.json如果存在确认里面的地址和 Key 与 TaoToken 一致不要混用两套凭证。Gradle 拉依赖失败。报错里常见Could not resolve或超时。先确认 JDK 是 17再确认settings.gradle里的仓库地址没被改坏如果是公司网络检查是否需要配置 Gradle 的仓库镜像。别去改 Forge 版本号硬凑版本对不上会引发一堆连锁错误。模组加载了但生物不生成。检查生物注册用的实体类型有没有加到EntityType注册表以及生成规则Spawn Placement有没有配。鹅要生成在森林、平原、丛林木乃伊在沙漠这些生物群系标签要写对。身份物品拿不到检查物品有没有注册进创造模式标签页或者扭蛋机的掉落逻辑有没有触发。排错时记住一个原则先用 curl 把 API 侧和 Key 侧的问题隔离掉再回头看模组代码。这样能省一半时间。6. 把链路固定下来后续开发与统一通道的用法环境跑通之后建议把几个习惯固定下来后面加身份物品、加生物会顺很多。第一三件套只维护一份。Base URL、Key、Model ID 统一放在taotoken.local.properties和运行参数里代码里不要出现第二份硬编码。以后换模型只改 Model ID换 Key 只改本地文件不用满项目搜。第二模组里所有需要 AI 能力的地方都走同一个封装方法。比如你后面要给鹈鹕、秃鹫加对话或者给扭蛋机加随机身份描述都调askTaoToken这一层别每个类各写一套 HTTP 请求。这样出错时只查一个地方。第三验证顺序固定成「curl 通 → build 成功 → runClient 进游戏 → 触发一次调用」。任何一步不过先解决这一步别跳。第四Key 不进 Git。.gitignore里加上taotoken.local.properties提交前扫一眼有没有误提交。如果已经提交了去控制台把那个 Key 禁用并重新生成。后续你要发布 1.18 或 1.16 版本时Forge 版本和 JDK 要求会变1.16 用 JDK 81.18 用 JDK 17但 TaoToken 这一侧的三件套不变Base URL 还是https://taotoken.net/api换的只是模组侧的 Forge 配置。把通道和模组版本解耦是这套做法最省心的地方。如果你在接入过程中卡在某个具体报错先去接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照参数再去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态。想先验证模型返回是否正常用模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条最快。长期做模组和 Agent 开发的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 更合适。
阅读完成 · 觉得有帮助？
