Presenton Mac App Store 构建实战MAS 打包的证书、Profile 与脚本完整避坑指南【免费下载链接】presentonOpen-Source AI Presentation Generator and API (Gamma, Canva, Beautiful AI, Decktopus, Presentations AI Alternative)项目地址: https://gitcode.com/GitHub_Trending/pr/presenton把 Electron 应用送进 App Store最劝退的往往不是写代码而是证书和 provisioning profile 这一套 Apple 的规矩。Presenton 是一个内置 Next.js 前端与 FastAPI 后端的 AI 演示文稿生成器仓库已经把 Mac App Store 构建的工程化配置铺好了沙盒 entitlements 文件、build.js构建脚本、npm 目标脚本全部就位你要做的只是补齐 Apple 开发者账号侧的四样东西然后跑一条命令。这篇按一次真实构建的动线走先备好材料再执行打包最后处理报错。先扫两张表目标、命令与环境变量这节解决最高频信息 30 秒拿到的问题后面所有环节都是这两张表的展开。构建目标与所需证书构建目标用途npm 命令在electron/下执行所需证书dmg不走 App Store 的直接下载分发npm run build:all:mac:signedDeveloper ID Application 公证凭据mas-dev注册 Mac 上的沙盒内测npm run build:all:mas-devApple DevelopmentmasApp Store 提交npm run build:all:masApple Distribution 3rd Party Mac Developer Installer两张证书缺一不可三个目标全部由PRESENTON_MAC_TARGET环境变量驱动上面三个 npm 脚本内部已经设好你不必手动指定。两个关键身份标识写死在 build.js 顶部Bundle ID 为com.presenton.presentonTeam ID 为S6W5C54KL6同时通过mac.extendInfo.ElectronTeamID写进应用。环境变量速查变量用于说明PRESENTON_MAC_TARGET全部由 npm 脚本设置用脚本时别手动设PRESENTON_MAS_DEV_IDENTITYmas-dev开发签名身份如Apple Development: Your Name (TEAMID)PRESENTON_MAS_DISTRIBUTION_IDENTITYmas分发身份如Apple Distribution: Your Org (TEAMID)PRESENTON_MAS_IDENTITYmas分发身份的别名CSC_NAME两种 MAS 目标目标专属变量没设时的回退PRESENTON_APP_STORE_VERSIONmasApp Store 版本号x.y.zpackage 版本带-beta后缀时必填PRESENTON_APP_STORE_BUILDmasApp Store build 号不设则默认取短版本号PRESENTON_CODESIGN_TIMESTAMPmas/dmg设为1恢复 codesign 时间戳默认本地打包用--timestampnonePRESENTON_CODESIGN_TIMESTAMP_RETRIESmas/dmg时间戳失败重试次数默认 4准备阶段四样材料一次备齐这节解决构建前到底要向 Apple 要什么、本地要放什么的问题。材料顺序按 Apple 开发者工作流排证书 → App ID → Profile → entitlements。在 Xcode 里生成两张证书为什么是两张Apple Development 用于mas-dev沙盒内测Apple Distribution 用于mas商店构建。而mas构建实际要签名两个东西——应用本体和.pkg安装包所以 build.js 的resolveMasSigningIdentities会同时找应用证书Apple Distribution或3rd Party Mac Developer Application与安装包证书3rd Party Mac Developer Installer缺一就抛错退出。打开 Xcode →Settings→Accounts→ 选择你的团队 →Manage Certificates。点先创建Apple Development给内测构建用。再点创建Apple Distribution给商店构建用安装包证书3rd Party Mac Developer Installer通常随团队在 Portal 上签发导入钥匙串即可。在 Portal 注册一个匹配的 App ID去 Apple Developer Portal →Certificates, Identifiers Profiles→Identifiers→App IDs创建一个 macOS App ID取值填com.presenton.presenton。如果你用自己的 ID记得同步改掉 build.js 里的APP_ID否则签名和 profile 会互相不认识。下载两个 Provisioning Profile 放进 electron/build/Provisioning profile 可以理解为设备白名单通行证它把证书、App ID 和允许的机器绑在一起Apple 服务器凭它验证这个构建是否合法。两个目标各需要一份对应关系如下Profile类型绑定证书保存为开发 profilemacOS App DevelopmentApple Developmentelectron/build/AppleDevelopment.provisionprofile商店 profileMac App StoreApple Distributionelectron/build/MacAppStore.provisionprofile两个细节构建脚本按候选文件名列表查找mas-dev还接受AppleDev.provisionprofile、AppDev.provisionprofile作回退mas还接受AppDistri.provisionprofile。真实 profile 不要提交进 git——仓库里那个MacAppStore.provisionprofile.replace_me占位文件就是让你只提交待替换状态用的。放入后先验证能否解码cd electron # 两个文件都应能解码出 plist解码失败说明文件不对或已损坏 security cms -D -i build/AppleDevelopment.provisionprofile security cms -D -i build/MacAppStore.provisionprofileProfile 通常按年过期到期后重新下载替换本地文件即可。看清 entitlements 里每个开关管什么这节解决沙盒应用为什么能跑起来的问题。entitlements 是沙盒权限开关清单entitlements.mas.plist 逐项声明了主应用的能力com.apple.security.app-sandbox开启 App SandboxMAS 的硬性要求com.apple.security.application-groupsS6W5C54KL6.com.presenton.presenton让应用和组件共享数据容器com.apple.security.cs.allow-jit允许 JIT 编译Electron 渲染进程依赖它com.apple.security.network.client/com.apple.security.network.server允许发起和监听连接——Presenton 内置的 Next.js 与 FastAPI 本地服务全靠这两项com.apple.security.files.user-selected.read-write读写用户主动选定的文件导入文档、导出 PPTX 的路径com.apple.security.files.downloads.read-write读写下载目录。辅助进程的 entitlements.mas.inherit.plist 只有两项app-sandbox加com.apple.security.inherit意思是继承主进程的能力边界不额外开洞。执行阶段三条构建路径这节解决命令怎么跑、产物落在哪的问题。所有命令都在electron/目录下执行首次使用先跑npm run setup:env它会串起npm install、FastAPI 的uv sync、Next.js 依赖安装以及导出运行时与 ImageMagick 的准备。完整构建推荐首发路径会重建 Next.js、FastAPI、导出运行时再打包应用适合首次或大改动后# 路径一MAS 开发构建——只在开发 profile 注册过的 Mac 上能运行 PRESENTON_MAS_DEV_IDENTITYApple Development: Your Name (TEAMID) \ npm run build:all:mas-dev # 路径二MAS 分发构建——产物用于上传 App Store Connect # 当前 package.json 版本带 -beta 后缀PRESENTON_APP_STORE_VERSION 是必填项 PRESENTON_MAS_DISTRIBUTION_IDENTITYApple Distribution: Your Org (TEAMID) \ PRESENTON_APP_STORE_VERSION1.0.0 \ npm run build:all:mas只重跑打包阶段资源已经构建好、只想再跑一次 electron-builder 打包时比如刚改了签名身份PRESENTON_MAS_DEV_IDENTITYApple Development: Your Name (TEAMID) \ npm run dist:mac:mas-dev PRESENTON_MAS_DISTRIBUTION_IDENTITYApple Distribution: Your Org (TEAMID) \ PRESENTON_APP_STORE_VERSION1.0.0 \ npm run dist:mac:mas注意dist:*脚本依赖 build.js 里的资源就绪校验——它会逐一检查 FastAPI 二进制、LLM 模型元数据、Next.js standalone server、导出任务 runner 与 export-core 包任何缺失都会提前报错避免打出内置服务起不来的坏包。不走 App Store直接出签名 DMG只想产出签名并公证的磁盘映像、绕过商店审核时# 使用 Developer ID Application 证书需 Apple 公证凭据 npm run build:all:mac:signed这条路径的 Developer ID 证书、notarytool 凭据存储与 Gatekeeper 验证细节见 直接分发指南。带 beta 后缀的版本号坑当前仓库 package.json 的版本是0.9.11-beta带-beta后缀。mas目标的版本号推导逻辑build.js 中的getAppStoreBundleShortVersion是优先读PRESENTON_APP_STORE_VERSION必须匹配x.y.z三段点分整数否则直接抛错未设置时尝试从 package 版本截取(\d)\.(\d)\.(\d)前缀截取失败版本号根本不是语义化格式就抛 Cannot derive an App Store version from package version。PRESENTON_APP_STORE_BUILD走同样的校验风格1~3 段点分整数如42或1.0.1不设则回退为短版本号。所以 beta 版本构建mas时最省事的写法export PRESENTON_APP_STORE_VERSION1.0.0 # 商店版本号三段点分整数 export PRESENTON_APP_STORE_BUILD42 # build 号可选产物都落在 electron/dist/路径随架构arm64/x64略有不同典型布局electron/dist/ mas-dev-arm64/ # 开发签名的 .app仅限注册 Mac 运行 mas-arm64/ # 分发签名的 .app供 App Store Connect 处理 Presenton-version.pkg # 上传 App Store Connect 的 MAS 安装包 Presenton-version.dmg # 签名并公证的直接分发 DMGmas构建产出的.pkg就是最终上传 App Store Connect 的东西。排错五类高频报错的对照处理这节解决构建失败时怎么快速定位的问题。每条按报错长什么样 → 为什么会这样 → 一步修复展开。报错信息节选原因修复动作Missing MAS development/distribution provisioning profile. Expected: ...electron/build/里没有该目标对应的 profile 文件按上表把正确的.provisionprofile放入electron/build/报错信息里列出的就是它期望的文件名Found MAS ... provisioning profile, but macOS could not decode it: ...文件存在但security cms -D与openssl cms -verify都解不开——文件损坏、传错或占位文件从 Developer Portal 重新下载对应 profile 覆盖本地文件别把真实 profile 提交进 gitCannot derive an App Store version from package version 0.9.11-betapackage 版本提取不出x.y.z三段整数设置PRESENTON_APP_STORE_VERSION1.0.0再跑构建MAS development builds must be run on macOS because Apple signing tools are required.在非 macOS 平台如 Linux CI上跑了 MAS 目标换到有 Xcode 命令行工具xcode-select --install的 Mac 上执行Missing MAS signing identity.后列出已有身份清单钥匙串里缺应用证书或安装包证书之一或身份变量指向了开发证书按报错清单补装缺失证书到钥匙串分发构建不能使用 Apple Development 等开发身份脚本会显式拒绝沙盒内辅助程序不可执行FastAPI / 导出二进制打不开build.js 的afterPack钩子会先对打包后的二进制执行chmod 755并清理与目标架构不符的原生 prebuild 目录如果之后仍签名失败回到准备阶段那两份 entitlements确认沙盒应用被允许执行Contents/Resources/app/resources/下的辅助程序。进阶身份解析、时间戳、图标与内测限制这节面向要深度定制构建流程的读者日常跑通前两个阶段可以跳过。签名身份解析与构建前预检。mas目标的身份解析链是PRESENTON_MAS_DISTRIBUTION_IDENTITY→PRESENTON_MAS_IDENTITY→CSC_NAME→ 自动发现。脚本用security find-identity -v读全钥匙串取身份限定词后自动匹配应用证书 安装包证书这对组合并拒绝开发身份混入分发构建。正式启动打包前还会执行一次codesign预检在临时文件上用选中的分发身份真签一次30 秒超时——超时通常意味着 macOS 在等钥匙串/私钥授权弹窗此时按提示解锁登录钥匙串并允许 codesign 访问 Apple Distribution 私钥即可。时间戳开关。本地 MAS 打包默认给 codesign 追加--timestampnone不依赖 Apple 时间戳服务无网或受限网络下不会挂起。需要时间戳时设PRESENTON_CODESIGN_TIMESTAMP1恢复时间戳偶发失败的重试次数由PRESENTON_CODESIGN_TIMESTAMP_RETRIES控制默认 4 次指数退避。图标。默认 macOS 图标是electron/resources/ui/assets/images/presenton_short_filled.png。要为商店提供正式.icns放到electron/build/icon.icns并同步更新 build.js 的mac.icon字段生成图标集的源 PNG 在electron/build/icon.iconset/。本地沙盒测试的四条边界。MAS 签名的应用必须由mas或mas-dev目标产出普通 DMG 构建不具备同等的沙盒兼容性mas-dev构建只能在开发 profile 里注册过的 Mac 上启动适合 TestFlight 式内测mas分发构建通常无法在本地直接启动它的归宿是 App Store Connect 的处理与发布流水线mas-dev签名带--timestampnone见上时间戳开关本地签名与网络状态无关。下一步把 .pkg 交给 App Store Connect构建跑通后动作只剩一个把electron/dist/下mas产出的Presenton-version.pkg通过 App Store Connect 的上传入口提交等待审核后发布。之后每次发版记住固定三步确认 profile 未过期 → 递增PRESENTON_APP_STORE_VERSION与 build 号 → 重跑build:all:mas。延伸阅读仓库内相对路径macOS 开发 README——全部构建目标速查含npm run dev与 notarytool profilepresenton-notary说明Mac App Store Setup——本文对应的官方设置文档Direct Distribution——Developer ID 证书、公证与 DMG 验证流程build.js——签名身份解析、profile 校验与版本号推导的完整实现【免费下载链接】presentonOpen-Source AI Presentation Generator and API (Gamma, Canva, Beautiful AI, Decktopus, Presentations AI Alternative)项目地址: https://gitcode.com/GitHub_Trending/pr/presenton创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考