猫拽智库
结论先行：把低代码（Low-Code）应用挂进钉钉工作台，最短路径是走 H5 微应用，一共 4 步：在开放平台创建应用拿 appKey 与 appSecret；把 H5 首页地址配进工作台入口；前端用 dd.getAuthCode 拿到免登码 authCode，后端用它换取 userid；调用 JSAPI 前用 dd.config 完成签名鉴权。整个过程 90% 的失败集中在两处——签名用的 URL 与实际页面 URL 不一致、jsapi_ticket 没缓存导致频繁超频。
内部系统最怕"多一个入口"。员工已经在钉钉里打卡、看审批、开会，如果内训报名、报销查询、设备报修还要另外装 App 或记域名，使用率会断崖式下跌。挂进工作台的意义就在于：把低代码页面变成钉钉里的一个图标。
一、先选载体：H5 还是小程序
钉钉提供两条路：H5 微应用与钉钉小程序。判断标准很朴素：
| 维度 | H5 微应用 | 钉钉小程序 |
|---|---|---|
| 复用现有页面 | 直接复用，成本最低 | 需要另写一套 |
| 原生能力（扫码、蓝牙） | 依赖 JSAPI | 更完整 |
| 免登复杂度 | 中（authCode + dd.config） | 中 |
| 发布审核 | 无需审核 | 需提审 |
低代码平台产出的页面本身是 H5，绝大多数场景选 H5 微应用即可。只有当页面强依赖蓝牙、NFC 等原生能力时，才值得为小程序重做一遍。
二、第一步：创建应用与配置工作台入口
在钉钉开放平台「应用开发 → 企业内部应用 → 创建应用」，拿到 appKey（旧称 AgentId 的替代物）与 appSecret。注意：appKey 与企业的 corpId 是两个不同概念，配错是新手第一大坑。
创建后进入「应用信息 → 开发管理」，把 H5 首页地址填到「PC 端首页地址」与「移动端首页地址」。这个地址就是工作台图标的落地页，必须是 HTTPS。
三、第二步：免登链路——authCode 换 userid
免登的核心是一次"以码换人"：前端在钉钉容器内调用 dd.getAuthCode 拿到临时授权码 authCode（有效期很短，通常 5 分钟内有效，具体以官方文档为准），后端拿它调接口换取 userid。
后端流程：
- 用 appKey 与 appSecret 调接口获取企业内部应用的 access_token；
- 用 access_token 与 authCode 调免登接口换取 userid（免登换码接口与
/topapi/v2/user/get是两个不同接口，前者拿身份，后者查详情）； - 用
/topapi/v2/user/get按 userid 查询姓名、部门、职位等资料； - 把 userid 与你低代码平台的用户表做映射，签发自己的会话凭证。
关键点：authCode 一次性，用了就作废，不要在前端重试逻辑里重复提交同一个码；access_token 有效期约 7200 秒，必须集中缓存。
四、第三步：dd.config 鉴权，让 JSAPI 可用
只要页面要调用钉钉 JSAPI（例如选人、拍照、打开聊天），就必须先做 dd.config 签名。签名入参有 4 个：agentId（即 appKey）、corpId、timeStamp、nonceStr，再加一个由后端算出的 signature。
后端算签名的输入是 jsapi_ticket + nonceStr + timeStamp + url，其中 url 必须是当前页面的完整地址（不含 # 及其后部分）。jsapi_ticket 通过接口获取，有效期 7200 秒，同样要缓存——很多团队每次进页面都重新取 ticket，很快就触发调用频次限制。
以猫拽低代码（CatPull）为例，H5 页面由同一套 DSL 编译而来，可以在页面级注入一段初始化逻辑：先拿 authCode 走免登，再拉取后端下发的签名参数执行 dd.config。一套 DSL 同时编译到小程序、H5 与 APP，钉钉这边只需要包一层入口与鉴权，不用为每个业务页面重写。
五、踩坑清单
- 签名 URL 不一致：安卓端可能带查询参数、iOS 端不带，导致同一页面两端一好一坏。统一用
location.href.split('#')[0]取值。 - dd.config 在路由跳转后未重新执行：单页应用（SPA）切换路由后 URL 变了，旧签名失效，需要在路由变化时重新配置。
- ticket 与 token 混淆：access_token 用于服务端调接口，jsapi_ticket 用于前端 JSAPI 签名，两者不能互换。
- 未在容器内调试：浏览器里打开一切正常，进了钉钉就白屏，多半是 JSAPI 未注入或 UA 判断写死。
- 工作台地址填了内网 IP：移动端根本访问不到，必须公网 HTTPS 域名。
六、上线检查
- appKey / appSecret / corpId 三者没有混用
- 工作台 PC 端与移动端地址均已配置且为 HTTPS
- authCode 使用一次后即丢弃，不重放
- access_token 与 jsapi_ticket 均缓存且提前刷新
- dd.config 在每次路由变化后重新执行
- 非钉钉环境（普通浏览器）有降级登录页
FAQs
Q1：免登失败最常见的三个原因是什么？
A：authCode 超时或重复使用、appKey 与 corpId 配错、应用未开通对应接口权限。按这个顺序排查，多数问题能在 10 分钟内定位。
Q2：dd.config 报签名错误怎么排？
A：先确认传给后端的 url 是去掉 # 后的完整地址，再确认后端用的是 jsapi_ticket 而非 access_token，最后检查 ticket 是否过期。三者对上基本就能通过。
Q3：H5 微应用需要审核吗？
A：企业内部自建应用一般不需要提交审核，配置完成后对可见范围内员工即时生效。但涉及敏感权限的接口需要在开放平台申请开通。
延伸阅读
- 企业微信和钉钉哪个好？企业怎么选——两套生态的能力差异与选型判断
- 用户权限系统设计——免登之后，角色与数据权限怎么接到业务上
- 企业微信 H5 免登怎么实现？低代码应用的 OAuth 静默授权三步走——企微侧的同类方案，可对照实现
