Zoom Meeting SDKmacOS环境变量配置与后端签名指南 —— knowledge-work-plugins【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本文围绕 macOS Meeting SDK 环境变量参考 展开系统讲解ZOOM_SDK_KEY、ZOOM_SDK_SECRET、ZOOM_ZAK等 6 个核心环境变量的含义、必填条件与获取途径并结合 zoom-plugin 技能树中的签名 Playbook、授权参考与 macOS Join/Start 流程文档说明这些变量如何驱动后端签名生成 桌面端短时效令牌消费的完整认证链路帮助你在 macOS 桌面应用中完成 Meeting SDK 的凭据配置与故障排查。一、文档定位macOS 技能树中的凭据参考在 knowledge-work-plugins 仓库中Zoom 插件以 partner-built 技能包形式组织。macOS Meeting SDK 技能的入口是 SKILL.md其 Start Here 清单将环境变量参考列为第 7 步文档说明该表被定位为集成后期的凭据核对单——先理解架构与生命周期最后对照环境变量逐项确认。该文档与 通用 Meeting SDK 环境变量参考、Android 版环境变量参考 构成一套平台共享 平台特化的凭据文档体系。需要说明的是Meeting SDK 的 JWT 签名必须服务端生成因此这些环境变量主要分布在后端签名服务而非 macOS 客户端本地。从 macOS 架构文档 的层次模型看App shell → Meeting coordinator → SDK service/controller → Backend signing/token service这条链路中环境变量中的密钥对Key/Secret只应出现在最底层的后端签名服务层这是理解下文所有安全约束的前提。二、六个核心环境变量逐项解析原文档给出的完整变量表如下完整继承自 macOS 环境变量参考VariableRequiredPurposeWhere to findZOOM_SDK_KEYYesSDK signing identityZoom Marketplace - Meeting SDK app - App CredentialsZOOM_SDK_SECRETYesServer-side signing secretZoom Marketplace - Meeting SDK app - App CredentialsZOOM_MEETING_NUMBERJoin/startMeeting identifierZoom invite / web portal / Meetings APIZOOM_MEETING_PASSWORDConditionalMeeting passcodeZoom invite details / Meetings APIZOOM_ROLEYesSignature role (0attendee,1host)App business logicZOOM_ZAKHost startHost authorization tokenZoom REST API token flow2.1 密钥对ZOOM_SDK_KEY与ZOOM_SDK_SECRET两者均必填且都来自 Zoom Marketplace 中 Meeting SDK 应用的 App Credentials 页面ZOOM_SDK_KEY签名身份标识issuer identity。它会出现在 JWT 的sdkKeyclaim 中用于 Zoom 侧识别哪个 Marketplace 应用发起了这次认证请求。ZOOM_SDK_SECRET签名密钥仅用于服务端 HS256 签名永远不应出现在 macOS 客户端、Xcode 工程或提交到版本库的.env文件中。通用环境变量参考 对此有明确表述Never exposeZOOM_SDK_SECRETin frontend/mobile clientsmacOS 版 Notes 则进一步要求Keep signing on backend。2.2 会议标识ZOOM_MEETING_NUMBER与ZOOM_MEETING_PASSWORDZOOM_MEETING_NUMBERJoin/start 流程均需要的会议号可来自 Zoom 会议邀请、Web 门户或 Meetings API。签名 Playbook 强调meetingNumber必须为纯数字在 JWT 中对应mnclaim格式错误是Invalid signature / Invalid Parameter类报错的常见根因。ZOOM_MEETING_PASSWORD条件必填——仅当会议设置了密码时需要。缺失或字段名写错时失败现象往往看起来像认证问题Playbook 特别提到 Web 端ZoomMtg.join的 key 是驼峰式passWordmacOS 原生接入虽不涉及该 API 名但passcode 缺失/错配导致 join 失败的排查思路通用。2.3 角色ZOOM_ROLEZOOM_ROLE必填取值只有两种值含义对应流程0attendee参会者Join 流程1host主持人Start 流程该值由应用业务逻辑决定表格中 Where to find 一栏标注 App business logic并直接写入 JWT 的roleclaim。角色与实际行为必须一致用role1签了名却去 join或反向是签名 Playbook 列出的典型失败模式之一。2.4 主持人授权令牌ZOOM_ZAKZOOM_ZAK仅在主持人发起Host start流程中需要是 Zoom REST API token 流签发的 host authorization token用于证明发起会议的这个人确实有权以主持人身份开始这个会议。结合 macOS Join/Start 模式文档Join参会者后端下发短时效签名 → 初始化/认证 SDK 并校验回调 → 用会议号 密码加入 → 注册会议 delegates。Start主持人后端同时提供ZAK 角色匹配的签名→ 以 host token 执行 start 流程 → 权限校验通过后启用主持人专属控制。Playbook 还提示了4003 Invalid Parameter错误Web start 流程常见多为角色不匹配或缺少主持人侧要求通常是缺 ZAK。macOS 侧虽无完全相同的错误码语义但host start 缺少 ZAK 导致失败属于同一类参数缺口。三、运行时令牌MEETING_SDK_JWT与 JWT 结构六个环境变量都是静态配置而真正传递给 SDK 的是运行时生成的短时效签名。通用环境变量参考 单列了一节 Runtime-only valuesMEETING_SDK_JWT(generated signature) —— Generate server-side and keep short-lived.授权参考 给出了 JWT 的 claim 结构与生成范式Claim说明sdkKeySDK Key对应ZOOM_SDK_KEYmn会议号对应ZOOM_MEETING_NUMBERrole0 参会者1 主持人对应ZOOM_ROLEiat签发时间戳exp过期时间戳tokenExp令牌过期时间戳仓库给出的短时效令牌生成示例Node.js摘自 authorization.mdconst jwt require(jsonwebtoken); function generateSignature(sdkKey, sdkSecret, meetingNumber, role) { const iat Math.floor(Date.now() / 1000) - 7200; // 2 hours ago const exp Math.floor(Date.now() / 1000) 10; // 10 seconds from now const payload { sdkKey: sdkKey, mn: meetingNumber, role: role, iat: iat, exp: exp, tokenExp: exp }; return jwt.sign(payload, sdkSecret, { algorithm: HS256 }); }其中两处取值有明确的工程理由均出自该文档exp仅比生成时刻晚 10 秒——令牌在加入会议前一刻才生成10 秒窗口足够且把泄露窗口压到最小iat回填 2 小时-7200——是为了满足exp - iat 2 hours的约束同时配合临近使用时才生成的策略保证安全。Playbook 补充了时钟约束iat/exp要reasonable 并考虑时钟偏差server time matters这也是本地能跑、生产挂掉类问题的典型原因之一生产服务器时钟漂移 环境里加载了不同的 Secret。安全基线小结综合原文档 Notes 与 授权参考 的 Do/Dont 表DoDont服务端生成签名在客户端代码暴露 SDK Secret使用短过期时间使用长效令牌先校验用户再生成签名为未认证用户生成签名桌面分发时把运行时令牌处理移出受检配置原文档 Notes 明确要求将 runtime token 处理写进 checked-in configs四、变量如何映射到 macOS 生命周期macOS 生命周期文档 给出了六步核心序列SDK 初始化 → SDK 认证回调成功 → join/start 分支选择 → 会议 controller 注册与功能激活 → leave/end 处理 → SDK 清理。环境变量在此序列中的位置可以归纳为初始化前后端已按ZOOM_SDK_KEY/SECRETZOOM_MEETING_NUMBERZOOM_ROLE生成MEETING_SDK_JWThost start 场景还需 ZAK 就绪认证回调后用签名host 场景含 ZAK执行 join 或 start失败域对照文档列出的四类失败域与变量的映射非常直接——auth/signature mismatch 对应密钥对或mn/role配置错误join/start 参数 mismatch 对应会议号/密码/ZAK 缺失delegate/controller 顺序问题与角色权限recording、breakout、webinar问题则属于凭据正确但流程状态机错误的范畴不应误判为环境变量问题。5 分钟预检 Runbook 把凭据核对浓缩为三条 checklistMeeting SDK 应用凭据Client ID/Secret、后端生成的签名/JWT、以及meetingNumber/password 和 host start 所需的 ZAK——与本文变量表一一对应建议将其作为发布前最后一道人工核对。五、跨平台对比macOS 与 Android 的差异边界将 Android 版环境变量参考 与 macOS 版对照两表的六行变量定义逐字一致Required/Purpose/Where to find 完全相同说明 Zoom Meeting SDK 的签名凭据模型在移动端与桌面端是统一的。差异只体现在 Notes 措辞上Android 版强调Keep mobile client as consumer of short-lived tokens, not secret holder客户端只是短时效令牌消费者macOS 版强调For desktop distribution, keep runtime token handling outside checked-in configs桌面分发场景运行时令牌处理必须移出受检配置。从文档结构可以推断macOS 版多出的分发约束源于桌面 App 通常经 App Store 或独立分发渠道发布二进制与配置的暴露面不同于移动市场分发因此对runtime token 处理不落盘提出了独立要求。六、排查速查错误现象到变量的反向定位综合 签名 Playbook 与 Runbook 决策树可将常见故障反向映射回环境变量现象优先检查的变量/配置401 / signature 错误ZOOM_SDK_SECRET是否与环境匹配、mn是否纯数字、exp/tokenExp是否过期、服务器时钟偏差role1 签名却 join或反向ZOOM_ROLE与业务动作是否一致UI 已加载但无法加入Runbook UI loads but cannot joinZOOM_ROLE/ZOOM_ZAK/ZOOM_MEETING_PASSWORD字段或会议数据无效host start 报参数类错误如 4003 语义缺少ZOOM_ZAK或角色要求未满足本地正常、生产失败两套环境加载了不同的ZOOM_SDK_SECRET、生产时钟漂移另有一条 Playbook 的重要澄清如果把REST API OAuth token 或 Marketplace JWT app-type token混进来当 Meeting SDK 签名用应立即停止并澄清——它们不是 Meeting SDK 签名ZOOM_ZAK所在的 REST token 流只服务于 host 授权这一个环节不能替代签名本身。七、版本前提与仓库延伸阅读环境变量语义本身随 SDK 大版本基本稳定但 macOS 版本与兼容性文档 记录了本地 SDK 包版本v6.7.6.75900的观测基线并建议升级时锁定精确 SDK 包版本、重测 controller/delegate 契约优先验证 custom UI 特性annotation/share/immersive并维护主持人专属与 webinar 专属流程的发布检查单。这意味着本文的变量表适用于该文档树所捕获的当前 Meeting SDK 凭据模型若你升级了 SDK 主版本建议重新对照仓库文档确认签名 claim 是否有增删。延伸阅读索引均为仓库内相对路径核心文档macOS 环境变量参考、通用环境变量参考签名与授权authorization.md、signature-playbook.mdmacOS 流程与架构SKILL.md、join-start-pattern.md、lifecycle-workflow.md、architecture.md、RUNBOOK.md跨平台对照Android 环境变量参考一句话总结Meeting SDK 的环境变量本质上是一套后端签名配置 会话级会议参数的混合清单——密钥对ZOOM_SDK_KEY/SECRET属于长期静态配置且必须留在服务端会议号/密码/角色/ZAK 属于随会话变化的运行时输入而最终交给 macOS 客户端的只有短时效MEETING_SDK_JWT。把这条边界守住签名类故障的大部分排查路径就能直接落到具体变量上。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Zoom Meeting SDK（macOS）环境变量配置与后端签名指南 —— knowledge-work-plugins
Zoom Meeting SDKmacOS环境变量配置与后端签名指南 —— knowledge-work-plugins【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本文围绕 macOS Meeting SDK 环境变量参考 展开系统讲解ZOOM_SDK_KEY、ZOOM_SDK_SECRET、ZOOM_ZAK等 6 个核心环境变量的含义、必填条件与获取途径并结合 zoom-plugin 技能树中的签名 Playbook、授权参考与 macOS Join/Start 流程文档说明这些变量如何驱动后端签名生成 桌面端短时效令牌消费的完整认证链路帮助你在 macOS 桌面应用中完成 Meeting SDK 的凭据配置与故障排查。一、文档定位macOS 技能树中的凭据参考在 knowledge-work-plugins 仓库中Zoom 插件以 partner-built 技能包形式组织。macOS Meeting SDK 技能的入口是 SKILL.md其 Start Here 清单将环境变量参考列为第 7 步文档说明该表被定位为集成后期的凭据核对单——先理解架构与生命周期最后对照环境变量逐项确认。该文档与 通用 Meeting SDK 环境变量参考、Android 版环境变量参考 构成一套平台共享 平台特化的凭据文档体系。需要说明的是Meeting SDK 的 JWT 签名必须服务端生成因此这些环境变量主要分布在后端签名服务而非 macOS 客户端本地。从 macOS 架构文档 的层次模型看App shell → Meeting coordinator → SDK service/controller → Backend signing/token service这条链路中环境变量中的密钥对Key/Secret只应出现在最底层的后端签名服务层这是理解下文所有安全约束的前提。二、六个核心环境变量逐项解析原文档给出的完整变量表如下完整继承自 macOS 环境变量参考VariableRequiredPurposeWhere to findZOOM_SDK_KEYYesSDK signing identityZoom Marketplace - Meeting SDK app - App CredentialsZOOM_SDK_SECRETYesServer-side signing secretZoom Marketplace - Meeting SDK app - App CredentialsZOOM_MEETING_NUMBERJoin/startMeeting identifierZoom invite / web portal / Meetings APIZOOM_MEETING_PASSWORDConditionalMeeting passcodeZoom invite details / Meetings APIZOOM_ROLEYesSignature role (0attendee,1host)App business logicZOOM_ZAKHost startHost authorization tokenZoom REST API token flow2.1 密钥对ZOOM_SDK_KEY与ZOOM_SDK_SECRET两者均必填且都来自 Zoom Marketplace 中 Meeting SDK 应用的 App Credentials 页面ZOOM_SDK_KEY签名身份标识issuer identity。它会出现在 JWT 的sdkKeyclaim 中用于 Zoom 侧识别哪个 Marketplace 应用发起了这次认证请求。ZOOM_SDK_SECRET签名密钥仅用于服务端 HS256 签名永远不应出现在 macOS 客户端、Xcode 工程或提交到版本库的.env文件中。通用环境变量参考 对此有明确表述Never exposeZOOM_SDK_SECRETin frontend/mobile clientsmacOS 版 Notes 则进一步要求Keep signing on backend。2.2 会议标识ZOOM_MEETING_NUMBER与ZOOM_MEETING_PASSWORDZOOM_MEETING_NUMBERJoin/start 流程均需要的会议号可来自 Zoom 会议邀请、Web 门户或 Meetings API。签名 Playbook 强调meetingNumber必须为纯数字在 JWT 中对应mnclaim格式错误是Invalid signature / Invalid Parameter类报错的常见根因。ZOOM_MEETING_PASSWORD条件必填——仅当会议设置了密码时需要。缺失或字段名写错时失败现象往往看起来像认证问题Playbook 特别提到 Web 端ZoomMtg.join的 key 是驼峰式passWordmacOS 原生接入虽不涉及该 API 名但passcode 缺失/错配导致 join 失败的排查思路通用。2.3 角色ZOOM_ROLEZOOM_ROLE必填取值只有两种值含义对应流程0attendee参会者Join 流程1host主持人Start 流程该值由应用业务逻辑决定表格中 Where to find 一栏标注 App business logic并直接写入 JWT 的roleclaim。角色与实际行为必须一致用role1签了名却去 join或反向是签名 Playbook 列出的典型失败模式之一。2.4 主持人授权令牌ZOOM_ZAKZOOM_ZAK仅在主持人发起Host start流程中需要是 Zoom REST API token 流签发的 host authorization token用于证明发起会议的这个人确实有权以主持人身份开始这个会议。结合 macOS Join/Start 模式文档Join参会者后端下发短时效签名 → 初始化/认证 SDK 并校验回调 → 用会议号 密码加入 → 注册会议 delegates。Start主持人后端同时提供ZAK 角色匹配的签名→ 以 host token 执行 start 流程 → 权限校验通过后启用主持人专属控制。Playbook 还提示了4003 Invalid Parameter错误Web start 流程常见多为角色不匹配或缺少主持人侧要求通常是缺 ZAK。macOS 侧虽无完全相同的错误码语义但host start 缺少 ZAK 导致失败属于同一类参数缺口。三、运行时令牌MEETING_SDK_JWT与 JWT 结构六个环境变量都是静态配置而真正传递给 SDK 的是运行时生成的短时效签名。通用环境变量参考 单列了一节 Runtime-only valuesMEETING_SDK_JWT(generated signature) —— Generate server-side and keep short-lived.授权参考 给出了 JWT 的 claim 结构与生成范式Claim说明sdkKeySDK Key对应ZOOM_SDK_KEYmn会议号对应ZOOM_MEETING_NUMBERrole0 参会者1 主持人对应ZOOM_ROLEiat签发时间戳exp过期时间戳tokenExp令牌过期时间戳仓库给出的短时效令牌生成示例Node.js摘自 authorization.mdconst jwt require(jsonwebtoken); function generateSignature(sdkKey, sdkSecret, meetingNumber, role) { const iat Math.floor(Date.now() / 1000) - 7200; // 2 hours ago const exp Math.floor(Date.now() / 1000) 10; // 10 seconds from now const payload { sdkKey: sdkKey, mn: meetingNumber, role: role, iat: iat, exp: exp, tokenExp: exp }; return jwt.sign(payload, sdkSecret, { algorithm: HS256 }); }其中两处取值有明确的工程理由均出自该文档exp仅比生成时刻晚 10 秒——令牌在加入会议前一刻才生成10 秒窗口足够且把泄露窗口压到最小iat回填 2 小时-7200——是为了满足exp - iat 2 hours的约束同时配合临近使用时才生成的策略保证安全。Playbook 补充了时钟约束iat/exp要reasonable 并考虑时钟偏差server time matters这也是本地能跑、生产挂掉类问题的典型原因之一生产服务器时钟漂移 环境里加载了不同的 Secret。安全基线小结综合原文档 Notes 与 授权参考 的 Do/Dont 表DoDont服务端生成签名在客户端代码暴露 SDK Secret使用短过期时间使用长效令牌先校验用户再生成签名为未认证用户生成签名桌面分发时把运行时令牌处理移出受检配置原文档 Notes 明确要求将 runtime token 处理写进 checked-in configs四、变量如何映射到 macOS 生命周期macOS 生命周期文档 给出了六步核心序列SDK 初始化 → SDK 认证回调成功 → join/start 分支选择 → 会议 controller 注册与功能激活 → leave/end 处理 → SDK 清理。环境变量在此序列中的位置可以归纳为初始化前后端已按ZOOM_SDK_KEY/SECRETZOOM_MEETING_NUMBERZOOM_ROLE生成MEETING_SDK_JWThost start 场景还需 ZAK 就绪认证回调后用签名host 场景含 ZAK执行 join 或 start失败域对照文档列出的四类失败域与变量的映射非常直接——auth/signature mismatch 对应密钥对或mn/role配置错误join/start 参数 mismatch 对应会议号/密码/ZAK 缺失delegate/controller 顺序问题与角色权限recording、breakout、webinar问题则属于凭据正确但流程状态机错误的范畴不应误判为环境变量问题。5 分钟预检 Runbook 把凭据核对浓缩为三条 checklistMeeting SDK 应用凭据Client ID/Secret、后端生成的签名/JWT、以及meetingNumber/password 和 host start 所需的 ZAK——与本文变量表一一对应建议将其作为发布前最后一道人工核对。五、跨平台对比macOS 与 Android 的差异边界将 Android 版环境变量参考 与 macOS 版对照两表的六行变量定义逐字一致Required/Purpose/Where to find 完全相同说明 Zoom Meeting SDK 的签名凭据模型在移动端与桌面端是统一的。差异只体现在 Notes 措辞上Android 版强调Keep mobile client as consumer of short-lived tokens, not secret holder客户端只是短时效令牌消费者macOS 版强调For desktop distribution, keep runtime token handling outside checked-in configs桌面分发场景运行时令牌处理必须移出受检配置。从文档结构可以推断macOS 版多出的分发约束源于桌面 App 通常经 App Store 或独立分发渠道发布二进制与配置的暴露面不同于移动市场分发因此对runtime token 处理不落盘提出了独立要求。六、排查速查错误现象到变量的反向定位综合 签名 Playbook 与 Runbook 决策树可将常见故障反向映射回环境变量现象优先检查的变量/配置401 / signature 错误ZOOM_SDK_SECRET是否与环境匹配、mn是否纯数字、exp/tokenExp是否过期、服务器时钟偏差role1 签名却 join或反向ZOOM_ROLE与业务动作是否一致UI 已加载但无法加入Runbook UI loads but cannot joinZOOM_ROLE/ZOOM_ZAK/ZOOM_MEETING_PASSWORD字段或会议数据无效host start 报参数类错误如 4003 语义缺少ZOOM_ZAK或角色要求未满足本地正常、生产失败两套环境加载了不同的ZOOM_SDK_SECRET、生产时钟漂移另有一条 Playbook 的重要澄清如果把REST API OAuth token 或 Marketplace JWT app-type token混进来当 Meeting SDK 签名用应立即停止并澄清——它们不是 Meeting SDK 签名ZOOM_ZAK所在的 REST token 流只服务于 host 授权这一个环节不能替代签名本身。七、版本前提与仓库延伸阅读环境变量语义本身随 SDK 大版本基本稳定但 macOS 版本与兼容性文档 记录了本地 SDK 包版本v6.7.6.75900的观测基线并建议升级时锁定精确 SDK 包版本、重测 controller/delegate 契约优先验证 custom UI 特性annotation/share/immersive并维护主持人专属与 webinar 专属流程的发布检查单。这意味着本文的变量表适用于该文档树所捕获的当前 Meeting SDK 凭据模型若你升级了 SDK 主版本建议重新对照仓库文档确认签名 claim 是否有增删。延伸阅读索引均为仓库内相对路径核心文档macOS 环境变量参考、通用环境变量参考签名与授权authorization.md、signature-playbook.mdmacOS 流程与架构SKILL.md、join-start-pattern.md、lifecycle-workflow.md、architecture.md、RUNBOOK.md跨平台对照Android 环境变量参考一句话总结Meeting SDK 的环境变量本质上是一套后端签名配置 会话级会议参数的混合清单——密钥对ZOOM_SDK_KEY/SECRET属于长期静态配置且必须留在服务端会议号/密码/角色/ZAK 属于随会话变化的运行时输入而最终交给 macOS 客户端的只有短时效MEETING_SDK_JWT。把这条边界守住签名类故障的大部分排查路径就能直接落到具体变量上。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考