企业官网建设流程全解析

• 桌面应用
• 开发工具

Quark Shell 是一个基于 WebKit 的 Mac 菜单栏（menubar）应用框架，让你只用 HTML 和 JavaScript 就能打造原生体验的工具，而无需编写任何原生代码。如果你准备用它开发的 Web 应用上架 Mac App Store，本文会帮你逐一理清 WebKit 沙盒、代码签名与系统兼容性这三类核心注意事项，让你的应用更顺利地通过 App Store 审核。

一、认识 Quark Shell：纯 Web 技术打造的菜单栏应用

Quark Shell 将 app/index.html 作为应用入口，app/preferences/目录下的 HTML 文件则作为设置页（例如 app/preferences/general.html）。页面中可以直接调用quark这个 JavaScript 对象，获得通知、弹出窗口、菜单栏图标、全局快捷键等系统能力，示例代码见 sample/index.html：

获取项目源码：

git clone https://gitcode.com/gh_mirrors/qu/quark-shell-mac

二、上架前提：沙盒与代码签名配置检查

2.1 App Sandbox 已默认开启

Mac App Store 强制要求应用开启沙盒（App Sandbox）。Quark Shell 主工程的 entitlements 中已包含：

• com.apple.security.app-sandbox（开启沙盒）
• com.apple.security.files.user-selected.read-write（用户选择的文件读写）
• com.apple.security.network.client（出站网络访问）

对应文件：quark-shell.entitlements。如果你的应用不需要额外权限，这一项基本不用动；若需要访问更多资源，请按需开启对应的 entitlement，并理解每一项都会接受审核员审视。

登录项辅助程序 quark-shell-helper.entitlements 中同样只开启了沙盒，符合 MAS 对 helper 的要求。

2.2 代码签名：App Store 分发必须配置

在 Xcode 的 Signing 中开启 "Automatically manage signing"，并选择 App Store 分发身份。代码签名对自动更新也是硬性要求——Docs/AutoUpdate.md 明确说明"出于安全考虑，必须正确签名才能启用自动更新"。

2.3 注意 LSUIElement：菜单栏应用要帮审核员"找到入口"

quark-shell-Info.plist 中设置了LSUIElement = true，即应用没有 Dock 图标、只驻留菜单栏。这类 agent 应用完全可以上架 Mac App Store，但建议在 App Store Connect 的审核说明（Review Notes）里写明"应用入口在菜单栏图标处"，避免审核员启动后以为应用没有响应。

三、WebKit 安全与行为要点

3.1 存储机制：LocalStorage 与 WebSQL 的位置

Quark Shell 使用传统NSWebView，其 LocalStorage 数据库被写入~/Library/Application Support/<Bundle Identifier>/LocalStorage，配置见 QSHAppDelegate.m。沙盒允许应用读写自己的 Application Support 目录，因此该机制在 MAS 下安全无虞。

此外，项目还开启了 WebSQL（默认 5MB 配额，见 QSHWebViewDelegate.m），但不支持 IndexedDB（README FAQ 中已说明）。如果你的 Web 应用依赖 IndexedDB，上架前需要改为使用 LocalStorage 或 WebSQL。

3.2 导航控制：外部链接一律交给系统浏览器

框架的导航策略只允许file:协议在 WebView 内加载，其余 URL 全部交给系统默认浏览器打开，见 QSHWebViewDelegate.m。这是一个很好的安全实践：网页内容无法"劫持"你的 WebView 窗口，上架前建议保留该逻辑。

3.3 发布前关闭调试模式

设置quark.debug = true会启用 Web 检查器相关的上下文菜单（见 QSHWebViewDelegate.m）。调试器本身只影响开发体验，但正式发布版本中请确认未开启 debug，保持发布构建干净。

四、上架前的兼容性排查清单

4.1 登录项 helper：记得改 bundle identifier

quark.setLaunchAtLogin(true)依赖 quark-shell-helper/ 这个登录项辅助程序，其 identifiercom.hackplan.quark-shell-helper硬编码在 QSHWebViewDelegate.m 中。上架前必须将 helper 与主应用的 bundle identifier 一起更换为自己的团队标识（README 中有相同提醒）。在较新的 macOS（Ventura 及以后）上，登录项功能建议使用 Apple 新的SMAppServiceAPI 实现，旧的登录项方案仍可用，但 helper 必须保持沙盒内运行。

4.2 Sparkle 自动更新与 Mac App Store 互斥

Quark Shell 内置 Sparkle 作为更新引擎（见 Podfile），它通过替换应用 bundle 完成自更新——而沙盒禁止这种行为，MAS 也不允许。上架 Mac App Store 的应用由 App Store 自动推送更新，因此：

• MAS 版本：移除或不使用quark.checkUpdate，把更新交给 App Store。
• 自分发版本：保留 Sparkle，参考 updater/SampleAppcast.xml 同目录下的示例 AppCast 配置。

4.3 通知 API 的弃用风险

quark.notify底层使用NSUserNotification/NSUserNotificationCenter（见 QSHWebViewDelegate.m）。该 API 自 macOS 11 起已弃用，目前仍能工作，但长期来看建议迁移到UNUserNotificationCenter，以规避未来系统版本的不兼容风险。

4.4 较旧的第三方依赖

Pdf 文件 依赖的 MASShortcut（2014 年分支）、Sparkle 1.13、RHPreferences 等库年代较久，在较新 Xcode / macOS 上编译时可能需要做弃用 API 或架构相关的兼容性修复。建议先用 Makefile 中的make release目标构建 Release 归档，确认工程可正常编译后再提交审核。

五、Mac App Store 上架流程步骤

1. 更换身份信息：修改 App 名称与 Bundle Identifier（详见 README.md 的 Integrating Web App 一节）。
2. 替换 Web 资源：删除app/目录后放入你自己的 HTML/JS 文件，入口保持为app/index.html。
3. 配置应用图标：替换 AppIcon.appiconset 中的各尺寸图标，Mac App Store 要求提供 1024×1024 的无 Alpha 图标（目录中已预留icon-1024.png槽位）。
4. 核对 entitlements：确认沙盒与网络权限如第二节所述。
5. 构建归档：在 Xcode 中选择 App Store 分发身份，Archive 后通过 Xcode Organizer 上传。
6. 完善 App Store Connect 信息：截图、描述中说明"这是菜单栏应用，图标位于屏幕右上角"，并在审核说明里描述如何唤起界面。
7. 提交审核：通过后即可上架，后续版本由 App Store 自动更新分发。

📌 小提醒：设置页的快捷键录制等原生组件说明见 Docs/Preferences.md，这些功能在沙盒下均可正常工作。

六、总结

用 Quark Shell 把 Web 应用上架 Mac App Store 的关键可以归纳为三句话：

• 沙盒：entitlements 默认配置已满足要求，网络访问与用户文件权限按需保留；
• 安全：保持"外部链接交给浏览器"的导航策略，发布前关闭 debug，注意通知 API 的弃用迁移；
• 兼容：更换 helper 的 bundle identifier、放弃 Sparkle 自更新（交给 App Store）、在较新 Xcode 上先验证编译。

按这份清单逐项核对后，你的菜单栏应用就能以稳定的姿态进入 Mac App Store 了。

• 桌面应用
• 开发工具