N.E.K.O.桌面版发布流程：Nuitka编译、代码签名与跨平台稳定版构建全解

N.E.K.O.桌面版发布流程：Nuitka编译、代码签名与跨平台稳定版构建全解

【免费下载链接】N.E.K.OA catgirl who lives with you in real time — reaching out first, sharing your media, and actually getting things done, powered by an embodied emotional engine.🐱❤️一只会主动找你玩的 AI 猫娘。项目地址: https://gitcode.com/gh_mirrors/ne/N.E.K.O

N.E.K.O. 是一只会主动找你玩的 AI 猫娘，它的桌面版要能稳定运行，离不开一条完整的发布流水线：Nuitka 编译生成独立后端、代码签名保证分发安全、跨平台构建覆盖 Windows / macOS / Linux。本文面向新手，用大白话讲清这套流程怎么运作、每个环节防住了什么坑，以及维护者如何产出一个可发布的稳定版。

先分清两类产物：Electron 前端 与 Nuitka 后端

理解 N.E.K.O. 桌面版，第一步是分清它由两部分组成：

• Electron 前端（窗口、托盘、Steam 集成、更新器）——来自配套的 N.E.K.O.-PC 仓库
• Python 后端（launcher.py入口的三服务架构）——由本仓库用 Nuitka 编译成projectneko_server独立可执行程序

只拿到 Python 后端可执行文件，是没有窗口、没有托盘、没有更新器的；反之亦然。这条区分在整个发布文档里被反复强调，见 docs/deployment/windows-exe.md。

Nuitka 编译：把 Python 项目冻成独立可执行程序

为什么选 Nuitka 而不是直接跑源码

Nuitka 会把 Python 代码直接编译成本机机器码，连同依赖库、数据文件一起打成一个目录（standalone 模式），用户无需安装 Python 环境即可运行。对 N.E.K.O. 这种带音频模型、Live2D 模型、大量静态资源的项目，"打包清单"就是编译阶段的核心工作。

内置插件的三级暂存策略

N.E.K.O. 自带 90 多个内置插件，每个插件的数据文件（plugin.toml、配置、前端页面）都不能漏。编译时遵循的固定顺序记录在 docs/contributing/nuitka-packaging.md：

1. 运行 scripts/prepare_nuitka_plugins.py 的prepare命令，按各插件的[tool.neko.build]规则生成精确的排除清单
2. 编译 Nuitka 启动器，产出dist目录
3. 再用install命令把插件"装进"构建好的发行目录
4. 最后跑一次完整性校验

这种"先编译、再装配插件"的方式，避免了把整个插件目录无脑塞进包里的粗放做法——文档明确警告不要恢复--include-data-dir=plugin/plugins这类一刀切写法，因为它会绕过暂存契约。

离线模型资产：编译前必须先备好

桌面版内置了向量记忆、语音端点检测、说话人识别等本地模型（onnx 权重文件）。这些权重不入库、运行时也不允许联网下载，因此必须在 Nuitka 编译前用 scripts/prepare_embedding_model.py 等脚本下载到位，随后打进发行包。

用静态检查代替盲目启动

打包后的启动器会拉起多个子服务，直接启动容易留下"看起来能跑、实际缺文件"的半成品。项目因此把静态完整性检查放在签名之前：

uv run python scripts/check_nuitka_dist.py dist/Xiao8 --plugin-stage build/nuitka-plugins

scripts/check_nuitka_dist.py 维护了一份"关键资产清单"，逐项断言发行包里必须存在的东西，例如：

• 主入口projectneko_server.exe与config/、static/、templates/三大目录
• 内置 Live2D 模型的.moc3与 4096 分辨率纹理（只查model3.json挡不住半截解包）
• 向量记忆模型的model_quantized.onnx具体权重文件（目录非空还不够，下载中断会留下空壳目录）
• 每个内置插件目录下必须有plugin.toml，否则运行时插件扫描结果为 0

它专门拦截三类历史事故：Nuitka 把数据目录里的.py当代码过滤掉、文件锁导致dist目录残留嵌套形成"能启动但缺 config/static"的半坏包、插件丢失plugin.toml。检查不通过就退出码非零，签名与 Electron 打包步骤不会执行。

代码签名：让稳定版可被用户与更新器信任

两级签名体系

稳定版发布采用"原生构建主机"策略：不在云端打 tag 触发构建，而是在 Windows / macOS / Linux 各自的构建机上原生编译、原生签名。签名分两级：

• 可执行文件签名：Windows 用代码签名证书、macOS 用开发者证书，由 scripts/build-desktop-release.ps1 调用本地可用的签名身份完成
• Portable 更新清单签名：用 Ed25519 密钥对更新 manifest 签名，产出配套的.sig文件，防止更新内容被篡改

发布脚本的关键参数示例（macOS arm64 架构）：

./scripts/build-desktop-release.ps1 -Version 0.8.4 ` -Platform macos -Architecture arm64 ` -ManifestSigningKeyPath /secure/portable-manifest-ed25519.pem ` -PreviousReleaseTag v0.8.3

脚本还复用姊妹仓库的 manifest 校验器（portable-update.js）做自校验。需要强调：签名脚本只负责签名与暂存，绝不创建 tag、上传 Release 或调用更新服务，发布动作由人工把关。

增量更新：更小的包，同样的可信

-PreviousReleaseTag参数会让脚本拉取上一版清单，当增量包比完整包更小时自动产出差分更新包——用户升级 0.8.3 → 0.8.4 时下载的体积显著变小，而信任链（manifest +.sig）保持不变。

跨平台稳定版构建：每个平台在原生主机上完成

全平台产物矩阵

一个稳定版发布必须凑齐以下全部产物（缺一项都不算合格发布）：

每个平台都在对应架构的原生主机上执行 Nuitka 编译（macOS 需按 arm64 / x64 各跑一遍 PowerShell 并显式指定-Architecture），再用 scripts/check_dist_arch.py 核对产物架构与目标一致，杜绝"在 x64 机器上打出 arm64 空壳包"之类的错位。

发布资产：上传前的最后防线

所有原生构建收齐到release-assets/<version>/后，运行 scripts/publish-desktop-release-assets.ps1 完成上传。它在上传前做了四道校验：

1. 暂存文件名与已发布 Release 逐一对应
2. 每个 Portable manifest 都有匹配的.sig文件
3. 已存在的 OSS 对象不可覆盖——重跑仅当 SHA-256 与暂存资产完全一致才放行
4. 注册镜像前，把每个 CDN 资产下载回来与暂存文件比对 SHA-256

OSS 凭证只保存在本地 ossutil 配置中，从不进入仓库文件，这也是签名与发布流程安全设计的一部分。

新手速查：发布前检查清单

• Nuitka 编译产物已通过check_nuitka_dist.py全部断言（含 Live2D 纹理、onnx 权重、插件plugin.toml）
• 六个平台产物（Win x64 / mac x64+arm64 / Linux x64+AppImage）齐备
• 每个 Portable manifest 都有对应.sig签名文件
• 架构校验（check_dist_arch.py）通过
• 发布前已在每台目标主机上实测签名身份可用
• 记住：Nightly 测试包未签名且随时被覆盖，稳定分发只走正式发布渠道

延伸阅读

这条"编译 → 静态校验 → 原生签名 → 跨平台收齐 → 哈希对账上传"的流水线，让 N.E.K.O. 桌面版在没有云端一键构建的情况下，依然能产出每个平台都签好名、每个文件都可验证的稳定发行版。

【免费下载链接】N.E.K.OA catgirl who lives with you in real time — reaching out first, sharing your media, and actually getting things done, powered by an embodied emotional engine.🐱❤️一只会主动找你玩的 AI 猫娘。项目地址: https://gitcode.com/gh_mirrors/ne/N.E.K.O