g4f (gpt4free) 多平台发布构建流水线全解：从版本 Tag 到 PyPI、Docker 与原生启动器

g4f (gpt4free) 多平台发布构建流水线全解从版本 Tag 到 PyPI、Docker 与原生启动器【免费下载链接】gpt4freeThe official gpt4free repository | various collection of powerful language models | opus 4.6 gpt 5.3 kimi 2.5 deepseek v3.2 gemini 3项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4free本文围绕 gpt4free 仓库的发布构建工作流docs/build-workflow.md所描述的完整打包流程展开讲清楚“推一个版本 Tag 之后一条 GitHub Actions 流水线如何并行产出 PyPI 包、多平台可执行启动器与 Docker 镜像并自动创建 GitHub Release”。读完本文你将掌握 g4f 各发布产物的触发方式、版本判定逻辑、各构建 Job 的源码级实现以及本地复现打包时的关键脚本与参数。一、工作流总览一条流水线七类产物docs/build-workflow.md指出仓库通过.github/workflows/build-packages.yml工作流在推送版本 Tag 时自动构建多种包格式。原文档列出的产物清单如下PyPI 包—— Python wheel 与源码分发包sdistWindows 可执行文件—— 独立 .exe文档描述为 Nuitka 时代产物见第四节Linux 可执行文件—— Linux 独立二进制macOS 可执行文件—— macOS 独立二进制x64 与 ARM64Debian 包—— 面向 Ubuntu/Debian 的 .debamd64、arm64、armhfWinGet 包—— Windows Package Manager 清单Docker 镜像—— 多架构容器镜像对照当前仓库中 build-packages.yml 的实际内容可以看到这条流水线由 4 个核心 Job 串联Job作用触发条件prepare解析版本号并判定是否为正式发布is_release每次运行必执行build-pypi构建 wheel sdist 并上传工件每次运行build-g4f-go交叉编译 Go 启动器并打包各平台 zip每次运行build-docker构建并推送 Docker 镜像armv7 / slim / 完整版仅正式发布is_release truecreate-release汇总所有工件创建 GitHub Release仅正式发布触发方式在 build-packages.yml 中定义得很直接监听所有 Tagtags: [*]同时支持workflow_dispatch手动触发并允许在手动触发时通过version输入框指定版本号留空则自动推导。触发构建的标准操作与原文档一致最典型的触发方式是推送版本 Taggit tag v1.2.3 git push origin v1.2.3手动触发方式对应workflow_dispatch打开仓库的 Actions 页签选择 Build All Packages 工作流点击 Run workflow可选地填写一个版本号。构建成功后原文档给出的产物去向与仓库实际配置完全吻合GitHub Releases所有可执行包与 PyPI 包作为 Release 资源PyPIpip install g4fDocker Hubdocker pull hlohaus789/g4f:latest仓库中的镜像名即hlohaus789/g4f见 build-packages.yml 的 metadata 配置WinGetwinget install g4f清单审批通过后生效Release 正文模板中给出的安装命令是winget install gpt4free见 build-packages.yml。二、版本如何被确定prepareJob 的三级版本来源原文档Version Handling一节提到工作流支持三种版本来源Git Tag发布首选、环境变量G4F_VERSION、手动输入。源码中这一逻辑集中在prepareJobbuild-packages.ymlif [[ ${GIT_REF} ~ ^refs/tags/ ]]; then G4F_VERSION${REF_NAME} # Tag 名即版本is_releasetrue IS_RELEASEtrue elif [[ -n ${{ inputs.version }} ]]; then G4F_VERSION${{ inputs.version }} # 手动输入is_releasefalse IS_RELEASEfalse else G4F_VERSION0.0.0-dev # 未指定时的开发版兜底 IS_RELEASEfalse fi要点有三只有 Tag 触发才算正式发布is_release输出被下游build-docker与create-release用作门禁if: needs.prepare.outputs.is_release true。也就是说手动触发且不带 Tag 的构建只产出工件与 Release 草稿之外的包不会推 Docker 镜像、也不会创建 Release。版本号向下传递的方式是needs.prepare.outputs.version各构建 Job 通过env: G4F_VERSION...注入例如 build-pypi 的构建步骤。setup.py直接读取该环境变量setup.py 中versionos.environ.get(G4F_VERSION)包名固定为g4f。原文档同时要求版本遵循 PEP 440 规范以保证 PyPI 兼容性。从当前仓库的 Job 名与产物命名g4f-go-${VERSION}-...、hlohaus789/g4f:${VERSION}-slim来看版本号会直接拼接进文件名与镜像 Tag因此含非法字符的版本号会在发布阶段产生难以检索的资源名。三、PyPI 包构建与发布build-pypiJob 和独立发布工作流build-pypiJobbuild-packages.yml的流程actions/setup-python安装 Python3.xpip install --upgrade pip后安装build与twine在G4F_VERSION环境变量下执行python -m build产出 wheel 与 sdist 到dist/用python -m twine check dist/*校验元数据分别以pypi-package合并、pypi-wheeldist/*.whl、pypi-sdistdist/*.tar.gz三个工件名上传供后续 Release Job 下载。值得注意的细节是build-packages.yml末尾的publish-pypiJob 目前是注释状态build-packages.yml即“推 Tag 建 Release 的这条流水线”本身不负责发 PyPI。真正把包发布到 PyPI 的是另一条独立工作流 publish-to-pypi.yml仅在github.repository xtekky/gpt4free且 ref 以refs/tags/开头时运行第 11 行避免 fork 仓库误发版用pypa/build构建 wheel 与源码包再以pypa/gh-action-pypi-publish基于 OIDCpermissions: id-token: write发布无需在密钥中存放 PyPI Token通过environment: pypi绑定发布环境属于典型的“构建与发布分离”设计。再看打包内容本身。setup.py 定义了最小运行依赖与按功能切分的 extras核心依赖INSTALL_REQUIRErequests、aiohttp、brotli、pycryptodome、nest-asyncio2—— 这也是build-g4f-goJob 中 pip 预装清单build-packages.ymlextras 包括all、slim、api、gui、image、search、webview、files、tray、local等例如api只需loguru、fastapi、uvicorn、python-multipart、a2wsgi、PyYAMLsetup.py命令行入口setup.pyg4fg4f.cli:main、g4f-mcpg4f.mcp.server:main、g4f-trayg4f.tray:_tray_main即安装后同时获得 g4f 客户端、MCP 服务器与托盘程序三个命令。四、原生可执行产物从 Nuitka 脚本到 g4f-go 启动器4.1 文档描述的 Nuitka 方案原文档指出可执行文件“使用 Nuitka 构建”并将 scripts/build-nuitka.sh 列为定制关键点。该脚本在仓库中确实存在且完整可用其设计值得拆解默认值与架构归一化build-nuitka.shPLATFORM默认取uname -sARCHITECTURE默认取uname -mVERSION取G4F_VERSION缺省0.0.0-dev输出目录OUTPUT_DIR缺省distx86_64/amd64 → x64、arm64/aarch64 → arm64、armv7l/armhf → armv7平台差异化参数build-nuitka.sh平台产物名关键参数Windowsg4f-windows-${VERSION}-${ARCH}.exe--windows-console-modeattach --onefilemacOSg4f-macos-${VERSION}-${ARCH}--macos-create-app-bundle --onefileLinuxg4f-linux-${VERSION}-${ARCH}--onefile通用参数与构建命令build-nuitka.sh--standalone --remove-output --no-pyi-file --include-packageg4f等最终以python -m nuitka ... g4f_cli.py打包并存在可选的 Windows 图标参数projects/windows/icon.ico构建后自检脚本最后检查产物文件是否存在失败则以非零码退出build-nuitka.sh。入口文件 g4f_cli.py 极薄先调用g4f.debug.enable_logging()打开日志再执行g4f.cli.main()注释明确说明它是“Nuitka 可执行构建的入口点”。配套还有 scripts/validate-nuitka.sh 验证脚本包含 5 项检查g4f_cli.py --help可运行、python -m nuitka --version可用、scripts/build-nuitka.sh可执行、工作流中包含 Nuitka 字样、工作流中存在matrix:架构矩阵。需要说明的是从当前工作流文本看可执行文件 Job 已改为 g4f-go 方案后两项断言与现状存在出入可以推断该验证脚本属于 Nuitka 时代的产物本地使用前应先对齐当前流水线。4.2 当前流水线实际方案g4f-go 交叉编译build-packages.yml 第 86 行注释写明 Executables (built with g4f-go, no Nuitka)可执行文件 Job 现在改为在 ubuntu-latest 上交叉编译 Go 启动器覆盖所有 OS/架构并在各 zip 中携带内嵌的 CPython 运行时。其步骤Go 1.22actions/setup-go依赖g4f-go/go.mod做缓存 Python 3.11预装 Python 侧核心依赖与rsync zip工具执行./fetch-python.sh获取并合并各平台 Python 运行时执行./build-all.sh交叉编译并逐平台打 zip上传合并工件g4f-go与各平台单独工件g4f-go-windows-amd64、g4f-go-linux-arm64等均设if-no-files-found: error缺产物即失败。g4f-go/build-all.sh 的默认目标矩阵为OSArch产物名linuxamd64g4f-golinuxarm64g4f-gowindowsamd64g4f-go.exedarwinarm64g4f-godarwinamd64g4f-goandroidarm64g4f-go构建命令形如CGO_ENABLED0 GOOS... GOARCH... go build -trimpath -ldflags -s -w -X main.Version$VERSION ...版本号通过-ldflags -X注入main.Version与G4F_VERSION一致缺省0.1.0。支持按 OS 过滤如./build-all.sh linux。一个值得记录的设计差异来自 build-all.sh 的头部注释运行时不在构建期嵌入启动器首次运行时从 python.org / python-build-standalone 下载./fetch-python.sh只负责固定尺寸与 SHA 校验值见runtime.json因此 Go 启动器本身可以脱离 Python 工具链独立构建。另外可以注意到工作流中定义了windows-386与freebsd-amd64的上传模式build-packages.yml而build-all.sh的默认目标表未包含这两项说明平台覆盖以工作流工件名清单为扩展边界从源码结构看后续可通过TARGETS表扩展。五、Docker 镜像构建仅正式发布、三类镜像build-dockerJobbuild-packages.yml仅在is_release true时运行流程为docker/setup-qemu-actiondocker/setup-buildx-action准备多架构构建环境docker/metadata-action生成hlohaus789/g4f的元数据 Tag使用仓库 secretsDOCKER_USERNAME/DOCKER_PASSWORD登录 Docker Hub这解释了原文档Troubleshooting中“Docker push 失败需检查仓库 secrets”一条依次构建并推送三类镜像均开启provenance: modemax与sbom: true镜像Dockerfile平台Tagarmv7 版docker/Dockerfile-armv7linux/arm/v7latest-armv7、${VERSION}-armv7slim 精简版docker/Dockerfile-slimlinux/amd64, linux/arm64latest-slim、${VERSION}-slim完整版docker/Dockerfilelinux/amd64由 metadata-action 生成含latest三类构建均通过build-args注入G4F_VERSION与 PyPI/可执行文件共用同一版本来源保证一次 Tag 内所有产物版本一致。六、系统级软件包Debian 构建脚本与 WinGet 现状原文档将.debamd64/arm64/armhf与 WinGet 清单列为支持格式并列出两个定制文件scripts/build-deb.sh与winget/manifests/。build-deb.sh 在当前仓库中完整可用其打包流程以G4F_VERSION缺省0.0.0-dev与ARCH缺省amd64为版本与架构变量清理并重建debian/g4f目录结构DEBIAN/、usr/bin、usr/lib/python3/dist-packages、usr/share/doc、usr/share/applications生成control文件Section: python、Priority: optional、依赖python3 ( 3.10), python3-pip, python3-aiohttp, python3-requestsbuild-deb.shpostinst脚本负责pip3 install五个核心依赖与setup.py的INSTALL_REQUIRE一致并建立/usr/local/bin/g4f → /usr/bin/g4f软链prerm负责卸载时移除软链build-deb.sh以python3 setup.py install --rootdebian/g4f --prefix/usr --install-lib/usr/lib/python3/dist-packages --install-scripts/usr/bin安装文件并将 README 压缩、LICENSE 拷为 copyright还生成桌面.desktop条目。关于 WinGet当前仓库快照中未发现winget/目录与build-packages.yml中对应的 manifest 生成 Job可以推断清单目前独立维护在 Windows Package Manager 的生态仓库中本仓库仅保留文档与 Release 说明winget install gpt4free作为用户入口。原文档提到的winget/manifests/模板路径属于规划性描述使用前建议以 Release 正文中的安装命令为准。七、Release 资产汇总create-releaseJob正式发布时create-releaseJobbuild-packages.yml完成最终汇聚下载pypi-package与g4f-go合并工件再用pattern: g4f-go-*merge-multiple: true拉取各平台单独工件通过find/cp将所有文件扁平化到./release/flat/并打印最终资产清单便于在日志中核对“缺失工件”对应原文档 Troubleshooting 第 3 条用softprops/action-gh-release以GITHUB_TOKEN创建 Releaseprerelease: false正文模板自动写入四个安装入口pip install g4f${VERSION}各平台g4f-go-${VERSION}-{os}-{arch}.zipwindows-amd64、linux-amd64、linux-arm64、darwin-amd64/arm64、freebsd-amd64winget install gpt4freedocker pull hlohaus789/g4f:${VERSION}与-slim变体。八、构建环境与本地定制原文档给出的本地构建要求Python 3.10、Nuitka、Docker、dpkg-deb仍然适用于按脚本复现各产物。结合仓库实际定制构建时的关键文件对照如下文件职责g4f_cli.py可执行构建入口Nuitka 方案入口setup.py包名、G4F_VERSION版本注入、依赖与 console_scriptsscripts/build-nuitka.shNuitka 各平台单文件构建脚本scripts/build-deb.shDebian 包构建脚本scripts/validate-nuitka.shNuitka 构建系统验证5 项检查g4f-go/build-all.sh / g4f-go/fetch-python.shGo 启动器交叉编译与 Python 运行时获取.github/workflows/build-packages.yml主工作流.github/workflows/publish-to-pypi.ymlPyPI 发布工作流本地构建示例均可在当前仓库查看后在自有环境执行# Nuitka 本地打包Linux x64 默认值 G4F_VERSION0.0.0-dev PLATFORMlinux ARCHITECTUREx86_64 OUTPUT_DIRdist bash scripts/build-nuitka.sh # Debian 包 G4F_VERSION0.0.0-dev ARCHamd64 bash scripts/build-deb.sh # Go 启动器仅构建 Linux G4F_VERSION0.0.0-dev ./g4f-go/build-all.sh linux九、版本规范、故障排查与安全实践原文档的 Troubleshooting 与 Security Notes 可以结合源码逐一落地构建失败检查 Python 版本与依赖。PyPI 侧工作流使用 Python3.xg4f-go 侧固定 3.11Debian 包声明python3 ( 3.10)依赖——从源码看 3.10 是各产物共同的下限版本错误确保版本符合 PEP 440。版本号会被setup.py写进 wheel 文件名、被build-all.sh拼进 zip 名、被 Docker 用作 Tag任何一处不合法都会产生难以定位的失败缺失工件build-g4f-go的各平台上传步骤均设置if-no-files-found: error缺产物会直接使 Job 失败create-release也会打印--- Final release assets ---清单便于核对Docker push 失败确认DOCKER_USERNAME/DOCKER_PASSWORD两个 secrets 已配置build-packages.yml且仅在 Tag 触发的正式发布中执行推送。安全方面原文档提到工作流采用受信任的 Action 版本、环境隔离与密钥管理。从 build-packages.yml 可以看到具体落实Docker 系列 Action 均锁定到具体 commit SHA如docker/setup-qemu-actionc7c53464...create-release仅申请contents: write最小权限publish-to-pypi.yml通过 OIDCid-token: write而非明文 Token 发布 PyPI仓库内没有硬编码凭证。十、向构建系统贡献修改原文档给出的贡献流程同样适用于本仓库先在本地测试可用scripts/validate-nuitka.sh做 Nuitka 链路自检或直接运行scripts/build-nuitka.sh、scripts/build-deb.sh验证本地打包同步更新文档如本文对应的docs/build-workflow.md考虑向后兼容build-packages.yml的 Job 名称、工件名pypi-package、g4f-go-*被create-release依赖重命名需同步修改下游多 Python 版本测试当前 Job 覆盖 3.xPyPI 构建与 3.11g4f-go 构建两条解释器链路改动依赖清单如setup.py的INSTALL_REQUIRE时应确认两条链路均通过。小结gpt4free 的发布体系是“一个 Tag、一条主工作流、四类下游渠道”。prepareJob 用三级来源确定版本并以is_release门禁正式发布动作build-pypi与独立的publish-to-pypi.yml分别负责构建与发布build-g4f-go以 Go 交叉编译替代了文档所述 Nuitka 方案Nuitka 脚本仍保留供本地使用build-docker在正式发布时推送 armv7/slim/完整三类多架构镜像create-release汇总所有工件并生成带四个安装入口的 Release 说明。理解这套“版本 → 工件 → 渠道”的映射关系是阅读或维护该仓库发布流程的关键。【免费下载链接】gpt4freeThe official gpt4free repository | various collection of powerful language models | opus 4.6 gpt 5.3 kimi 2.5 deepseek v3.2 gemini 3项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4free创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考