Gopeed 本地开发如何启动 API 后端与 Flutter 前端进行联调？

Gopeed 本地开发如何启动 API 后端与 Flutter 前端进行联调？

【免费下载链接】gopeedA fast, modern download manager for HTTP, BitTorrent, Magnet, and ed2k. Cross-platform, built with Golang and Flutter.项目地址: https://gitcode.com/GitHub_Trending/go/gopeed

Gopeed 由 Go 后端和 Flutter 前端两部分组成，前端源码位于ui/flutter目录。官方贡献指南建议通过 web 端进行开发调试：先用命令行启动 Go 后端 API 服务，再以 debug 模式启动 Flutter 前端，两者即可连通。本文按这条路径说明本地联调的完整操作：准备环境、启动后端、启动前端、判断联调是否生效，以及修改 API 模型和提交前的必要命令。

环境要求

README 的开发环境一节给出的最低要求是：

• Go 1.25+
• Flutter 3.41+

先获取代码：

git clone git@github.com:GopeedLab/gopeed.git

后续所有命令默认在仓库根目录下执行。

第一步：启动 Go API 后端

在仓库根目录执行：

go run cmd/api/main.go

这条命令就是 CONTRIBUTING.md「本地开发」一节指定的后端启动方式，服务默认端口为9999。

看 cmd/api/main.go 的源码可以确认它只用于本地开发（注释写明only for local development），启动参数是硬编码的，不需要也不应该手动修改：

cfg := &model.StartConfig{ Network: "tcp", Address: "127.0.0.1:9999", Storage: model.StorageBolt, WebEnable: true, }

也就是说，本地开发时后端通过 TCP 监听127.0.0.1:9999，使用 Bolt 存储。执行后终端保持前台运行，进程不退出即表示服务在运行。

第二步：以 debug 模式启动 Flutter 前端

在ui/flutter目录下以 debug 模式启动前端项目即可运行。web 端即以浏览器为目标设备，例如：

cd ui/flutter flutter run -d chrome

这里的关键在于 debug 模式下前端的 API 地址默认就指向 9999 端口。gopeed_transport.dart 中定义了const defaultWebApiPort = 9999;，并说明 debug 模式连接 9999 端口的后端，而 release 构建则使用页面自身的服务器来源。widget_test.dart 中的测试也固定了这一行为：debug 模式下 web API 基址为http://127.0.0.1:9999/。

所以只要第一步的后端还在运行，前端发出的 API 请求就会落到127.0.0.1:9999上，无需在前端再做任何连接配置。

如何验证联调生效

文档没有给出固定的成功日志，可以依据以下行为判断：

1. 后端进程正常驻留在go run cmd/api/main.go的终端里，没有退出报错。
2. debug 模式的 web 前端启动后，页面数据（任务列表等）通过 REST 接口从 9999 后端获取；前端能正常拉取数据并展示，说明前后端已连通。
3. 修改 Go 后端代码后重新执行go run cmd/api/main.go，前端下一次请求即为新逻辑的响应，可以用来快速验证后端改动。

按 backend-transport-architecture.md 的说明，Flutter 设置页会展示 API 服务实际运行状态、监听地址以及启动失败时的lastError，前端连不上后端时可以先到这里查看状态。

修改 api/models 时需要 build_runner

如果联调过程中要编辑ui/flutter/lib/api/model下的模型定义（.g.dart由 build_runner 生成），CONTRIBUTING.md 要求打开 build_runner watcher：

flutter pub run build_runner watch

提交前必须执行的格式化

CONTRIBUTING.md 要求每次提交前务必执行：

dart format ./ui/flutter

边界说明

• 官方推荐通过 web 端进行开发调试；桌面原生打包（c-shared构建 +flutter build windows/macos/linux）是另一条构建路径，见 README.md 的 Build 一节，不属于本文的本地联调流程。
• 贡献流程上，本项目只有main一个主分支：先 fork，在 fork 中开发，完成后向main提 PR（见 CONTRIBUTING.md）。

【免费下载链接】gopeedA fast, modern download manager for HTTP, BitTorrent, Magnet, and ed2k. Cross-platform, built with Golang and Flutter.项目地址: https://gitcode.com/GitHub_Trending/go/gopeed