按「复现现象 → 定位模块 → 查日志/权限 → 验证修复 → 记录预防」五步排查。每类问题均给出后台菜单路径与可执行检查清单，覆盖实施中最常遇到的 40+ 典型场景。内容依据宜搭官方帮助中心与算数科技项目交付经验整理。
10 大类
40+ 典型问题
症状速查矩阵
后台路径对照
场景演练 SOP
遇到问题时，建议按此顺序排查
1
复现并记录 — 记录操作账号、应用/表单名、时间点、报错原文或截图；多人复现可判断是账号问题还是配置问题。
2
区分环境 — 区分钉钉客户端 / 浏览器 / 移动端；自建宜搭与 SaaS 版后台入口不同，避免在错误环境查配置。
3
先查权限与发布状态 — 约 60% 的「功能异常」实为权限不足或流程/自动化未发布；优先在管理后台确认成员、角色、发布状态。
4
查运行日志 — 流程实例日志、智能助手Pro 运行记录、OpenAPI 调用日志（开放平台）是定位根因的关键依据。
5
小范围验证后推广 — 修改配置后先用测试账号验证，再通知业务方；重大变更前导出表单结构与权限快照备查。
症状速查：先对号入座，再下钻专题
约 60% 的「功能坏了」实为权限、发布状态或筛选条件问题。下表按用户可见现象反查最可能模块，避免从 API 或性能方向空耗时间。
| 用户看到的现象 | 优先怀疑 | 第一步去哪查 | 跳转 |
|---|---|---|---|
| 打不开应用 / 提示无权限 | 成员与角色 | 应用设置 → 成员与权限 | ② |
| 提交了但列表里找不到 | 数据权限 / 筛选 / 流程中 | 数据管理 → 重置筛选；查「我发起的」 | ③ |
| 审批一直停在某人 | 审批人失效 / 会签未齐 | 实例详情 → 流程图 / 审批记录 | ④ |
| 自动化没跑 / 跑了两次 | 未发布 / 触发条件 / 循环触发 | 智能助手Pro → 运行日志 | ⑤ |
| 公式不算数 / 联动不刷新 | 字段类型 / 引用路径 / 只读 | 表单设计器 → 公式编辑器 | ⑧ |
| 门户菜单缺页 / 手机端错位 | 门户未发布 / 角色可见性 | 门户设计 → 预览 → 发布 | ⑨ |
| 改完配置业务方看不到 | 设计态未发布 | 应用发布中心 → 对比版本 | ⑩ |
| 接口 401 / 403 | Token / 权限 / 白名单 | 钉钉开放平台 → 调用日志 | ⑥ |
| 列表打开要 10 秒以上 | 数据量 / 无索引 / 大字段 | 数据管理行数；检查默认筛选 | ⑦ |
后台入口速查（实施顾问常用路径）
组织钉钉工作台 → 宜搭 → 平台管理 → 组织管理 → 成员管理
应用权限我的应用 → 目标应用 → 应用设置 → 成员与权限 → 角色管理
数据权限表单/流程 → 数据管理 → 权限设置 → 数据权限组
流程运维流程表单 → 数据管理 → 实例详情 → 流程图 / 转交 / 退回
自动化日志应用内 → 智能助手Pro → 选择规则 → 运行日志
聚合表应用内 → 聚合表 → 刷新设置 / 手动刷新
API 调试open.dingtalk.com → 应用开发 → 宜搭 OpenAPI → 在线调试
发布应用编辑态 → 右上角「发布」→ 发布记录 / 版本对比
注意：宜搭「设计态」与「运行态」分离——在设计器里改完必须点发布，否则业务用户仍看到旧版。排查时先确认问题账号访问的是否为已发布版本。
① 登录与钉钉集成
钉钉扫码登录宜搭无反应或一直转圈
可能原因
宜搭未安装到企业、可见范围不含当前用户、浏览器拦截 Cookie、或自建版域名/CorpId 配置不一致。
排查步骤
- 钉钉管理后台 → 应用管理 → 确认「宜搭」已启用，可见范围包含测试账号所在部门
- 换 Chrome/Edge 无痕窗口；关闭「阻止第三方 Cookie」后重试
- 优先在钉钉客户端内打开工作台宜搭，排除浏览器插件干扰
- 自建部署：核对宜搭后台「集成配置」中 CorpId、回调域名与钉钉开放平台一致
提示「无权限访问」但钉钉账号正常
宜搭权限独立于钉钉通讯录：需在宜搭「组织管理 → 成员管理」中邀请或同步成员，并分配应用访问权限。仅加入钉钉部门不等于自动获得宜搭应用权限。
成员已从钉钉离职但仍能登录宜搭
宜搭成员状态需手动禁用或等待通讯录同步任务执行（通常 T+1）。管理员应在「成员管理」中及时禁用账号，并回收应用管理员、开发者等高权限角色。
多端登录后数据不同步
宜搭以服务端数据为准，客户端偶发缓存延迟。处理方式：下拉刷新列表；审批类操作优先在发起端完成；避免同时在 PC 与手机编辑同一条记录。
② 权限与组织架构
用户看不到应用或表单入口
按顺序排查：应用成员列表 → 应用内角色（管理员/开发者/访问者）→ 表单级权限组 → 门户/菜单是否发布到该角色。新成员默认无权限，需管理员在「应用设置 → 成员与权限」中显式添加。
能看到列表但查不到某些数据行
检查「数据权限」配置：全部数据 / 本部门 / 本人 / 自定义条件。列表视图上的筛选条件也会缩小可见范围，点击「重置筛选」对比。流程审批中的数据可能只在「待我处理」中可见。
字段可查看但无法编辑（按钮灰色）
原因常见有三：字段权限设为只读；记录处于流程节点中该字段被锁定；字段由公式/数据联动赋值导致只读。在表单设计器中检查字段「编辑权限」与「默认值/公式」配置。
部门架构同步后权限错乱
宜搭支持从钉钉同步组织架构，但角色绑定不会自动随部门变更。部门调整后应审查「按部门授权」的规则，必要时改为「按角色组」管理，降低组织变动带来的影响。
③ 表单与数据操作
提交成功但在数据管理中找不到记录
按优先级排查（约 5 分钟可定位 80% 案例）
- 数据权限：数据管理 → 权限设置 → 确认当前角色为「全部数据」或包含提交人；若仅「本人数据」，管理员账号看不到他人提交
- 列表筛选：点击「重置筛选」；检查是否默认筛选了「流程状态=审批中」导致已结束单被隐藏
- 流程占用：绑定流程的表单，新记录在「我发起的」「待我处理」中，未必出现在普通数据视图
- 自动化误删：智能助手Pro → 运行日志，筛选提交时间点前后是否有「删除数据」动作
- 多版本表单：确认查看的是与提交时相同的表单版本（发布变更后旧实例仍挂旧版）
字段校验不通过但看不出哪一项有问题
必填、格式、唯一性、自定义校验公式均会拦截提交。移动端错误提示较小，建议在 PC 端复现；检查子表单内是否有隐藏必填行；校验公式中引用空值时需用 IF 兜底。
附件上传失败或一直 0%
单文件大小受版本限制（免费版通常 ≤ 50MB，企业版可更高）；检查网络与钉钉/企业防火墙是否拦截上传域名；图片字段与附件字段限制不同；批量上传建议分批，单次不超过 20 个文件。
Excel 批量导入失败或部分行丢失
导入前准备
从数据管理导出官方模板，勿手改列顺序；成员/部门字段填 userid / 部门编码，非显示姓名。
失败处理
- 下载「错误报告」定位行号与字段；常见：日期非 YYYY-MM-DD、单选值不在选项列表、必填为空
- 单次 ≤ 5000 行；超大文件按月份拆分导入
- 导入不触发智能助手Pro——若需补跑，用定时任务或手动批量更新触发字段
- 导入后核对行数：数据管理总行数 − 导入前行数 ≈ 成功条数
子表单汇总金额计算不正确
主表汇总子表需使用 SUM 等聚合函数，引用路径应为「子表单.金额」而非主表字段。子表行数上限约 200 行（以当前版本文档为准），超出会导致保存失败或截断。
数据导出 Excel 乱码或列错位
使用 UTF-8 打开；关联表单字段导出为 ID 时需用 VLOOKUP 二次匹配；导出大量数据建议用「数据管理 → 导出」而非视图复制，超限时联系管理员分批导出。
④ 流程审批
提交后流程未发起
确认流程设计已「发布」且表单已绑定该流程版本；检查发起条件（如金额阈值）是否满足；发起人是否在流程允许的发起范围内；查看表单提交日志是否有流程引擎报错。
流程卡在某个节点不流转
诊断路径
- 打开该条数据 →「流程图」：当前节点高亮，查看「待处理人」是否为空或已离职
- 或签 / 会签：或签需任一通过；会签需全部通过——确认是否有人未处理
- 条件分支：检查分支条件字段类型（金额用数字组件，勿用文本比较）；空值走默认分支
- 审批人规则：「直属主管」类动态规则在组织不同步时会取不到人，改为固定角色组更稳
- 管理员：流程运维 →「转交」给在岗人员，或「退回」至可编辑节点
审批人收不到钉钉待办通知
① 钉钉「设置 → 新消息通知」中开启工作通知；② 宜搭应用消息推送权限是否开启；③ 审批人是否使用企业钉钉账号（非个人版）；④ 在钉钉工作台进入宜搭手动刷新待办；⑤ 检查是否被「勿扰」或「审批委托」规则转发走。
退回后数据状态异常或重复审批
退回目标节点需在设计时明确（上一节点 / 发起人）；退回后字段可编辑范围由节点配置决定；避免在退回同时触发智能助手Pro 修改同一字段，防止状态竞争。
⑤ 高级功能（聚合表 / 智能助手Pro / 数据工厂）
聚合表数据不更新或数字对不上
聚合表按设定频率刷新，非实时；修改源表单后需等待下一次同步或手动触发刷新。检查聚合条件、分组字段类型是否一致；关联字段变更后需重新保存聚合表配置。
智能助手Pro 配置了但不执行
五分钟检查表
- 规则状态是否为「已发布」（草稿不执行）
- 触发事件与实际操作是否一致：手动改字段不触发「仅新增」规则
- 条件里字段路径是否因改版变更（如子表字段重命名）
- 运行日志 → 查看「跳过 / 失败」及原因文案
- 批量导入、OpenAPI 写入：确认版本是否支持触发，必要时改定时同步
智能助手Pro 重复触发导致数据重复
避免「修改时触发」监听会被自身更新再次触发的字段；增加条件判断（如状态字段仅变更一次）；使用「仅当字段从 A 变为 B」类条件；关键写操作建议加唯一性约束或幂等校验。
数据工厂任务失败或超时
检查上游数据源连通性与字段映射；单任务数据量过大时拆分为多个节点或缩小时间窗口；查看任务运行详情中的失败行；输出目标表字段类型需与加工结果匹配。
⑥ API 与连接器
宜搭 OpenAPI 基于钉钉开放平台鉴权，常见 HTTP 状态码与处理建议如下（详见 宜搭 OpenAPI 文档）：
| 状态码 | 含义 | 常见原因 | 处理建议 |
|---|---|---|---|
| 401 | 鉴权失败 | accessToken 过期、AppKey/Secret 错误 | 重新获取 token；核对应用凭证是否轮换 |
| 403 | 无调用权限 | 应用未开通接口、IP 白名单限制 | 开放平台开通权限；配置服务器出口 IP |
| 404 | 资源不存在 | formUuid / instanceId 错误或已删除 | 用最新 ID；删除操作需幂等处理 |
| 429 | 限流 | 短时间请求过多 | 指数退避重试；合并批量接口 |
| 500 | 服务端错误 | 参数格式、字段类型不匹配 | 对照 API 文档检查 JSON 结构 |
连接器调用外部系统超时
确认对方接口公网可达且响应 < 30s；宜搭连接器有超时上限，慢接口应改为异步回调或中间层队列；检查鉴权头、Content-Type 是否与对方要求一致。
Webhook 回调收不到或验签失败
回调 URL 须 HTTPS 且公网可访问；核对签名算法与密钥；防火墙放行宜搭/钉钉回调 IP 段；先用 官方调试工具模拟推送验证接收端逻辑。
与 ERP / 数据库集成数据不一致
明确主数据源（宜搭为主或 ERP 为主）；用「增量同步 + 对账报表」而非全量覆盖；关键字段建立双向映射表；异常数据进入死信队列人工复核，避免脏写。
⑦ 性能与容量
表单打开慢或列表加载超时
单表数据量超过 10 万行后查询明显变慢；为常用筛选字段建索引；列表默认不加载大文本/附件字段；历史数据归档到「归档表」或导出冷存储；复杂关联改用聚合表预计算。
仪表盘图表刷新卡顿
单图表数据点建议 < 1 万；多图表引用同一数据源时可合并查询；避免实时拉取全量明细，改用聚合表或数据工厂预处理；高峰时段避开大批量导入与定时任务叠加。
版本配额不足（应用数 / 自动化次数）
各版本配额见订购页面；清理未使用应用与草稿自动化；合并相似智能助手Pro；升级套餐或联系宜搭商务扩容。算数科技渠道客户可协助评估版本与采购优化。
容量参考（实施建议，非官方 SLA）：
单表单活跃数据建议控制在 5–10 万行以内；子表单 ≤ 200 行/单；单次导入 ≤ 5000 行；智能助手Pro 避免分钟级高频触发。超规模场景应提前规划归档与数据中台方案。
⑧ 公式与数据联动
公式类问题占实施咨询量约 25%。宜搭公式在保存时计算，部分联动在字段变更时触发——先分清是「不算」还是「算错」。
主表汇总子表金额始终为 0
现象：子表已填多行金额，主表「合计」字段显示 0 或不更新。
- 公式须用聚合函数：SUM(子表单.金额)，不能直接写 子表单.金额
- 确认子表字段组件为「数字」而非「文本」，文本参与 SUM 会得 0
- 子表行在保存前未落库时，公式可能暂不计算——先保存草稿再查看
- 子表超过约 200 行时部分行可能被截断，导致汇总偏小（见容量说明）
IF / DATEDIF 公式报错或结果为空
现象：提交提示公式错误，或日期差、条件判断无结果。
- 空值兜底：IF(金额, 金额*0.13, 0)，避免 NULL 参与运算
- 日期组件引用直接写字段名，格式 YYYY-MM-DD；勿与文本字段混用 DATEDIF
- 比较运算符两侧类型一致：数字字段勿加引号
- 在公式编辑器用「调试」查看中间变量；复杂逻辑拆为多字段分步计算
数据联动 / 关联表单填充不生效
常见根因
联动条件字段未先填写；关联表单数据权限导致取不到目标行；联动目标字段为只读公式字段。
排查
- 按联动配置的「触发顺序」依次填字段，观察哪一步中断
- 用管理员账号测试：若管理员可联动而普通用户不行，查关联表单数据权限
- 联动赋值目标改为普通文本/数字字段，排除公式字段写入限制
唯一性校验「已存在」但列表搜不到
唯一性校验针对全表数据含无权限行；当前用户因数据权限看不到冲突记录。管理员用「全部数据」权限检索重复值，或导出全表对账后清理历史脏数据。
选项关联 / 级联下拉选项不全
检查选项数据源表单是否有过滤条件；数据权限是否限制选项可见范围；选项超过 500 条时考虑改用关联表单 + 搜索选择组件。
⑨ 门户与页面展示
门户菜单缺少某个表单 / 页面入口
- 门户设计器 → 检查菜单项是否绑定正确页面，且状态为「已发布」
- 菜单「可见角色」是否包含当前用户所属角色
- 子应用从主应用拆出后，门户链接可能仍指向旧路径，需更新菜单 URL
- 移动端与 PC 端可配置不同导航，分别预览钉钉内 H5 与浏览器
自定义页面图表 / 列表空白
数据源表单权限不足会导致组件无数据；检查页面筛选条件是否过严（如默认「本月」但无本月数据）；仪表盘组件引用的聚合表是否已刷新；设计态有数据而运行态无数据时，多为发布未同步。
手机端布局错乱、按钮点不到
表单设计 → 移动端布局单独调整，勿仅依赖 PC 自动适配；避免一行过多列；固定底栏按钮与钉钉原生栏重叠时，增加底部留白；在真机钉钉内测试，浏览器模拟不完全可靠。
打印模板缺字段 / 分页断裂
打印模板需单独配置字段映射；子表打印检查「展开行」设置；图片/附件字段打印受权限与文件大小影响；流程未结束时部分字段可能尚未赋值，在「审批完成」节点后再触发打印更稳。
⑩ 发布上线与版本管理
发布检查清单（上线前 10 项）
- 表单 / 流程 / 智能助手Pro / 门户均已点击「发布」
- 测试角色与生产角色权限组已区分，测试数据已清理或隔离
- 流程审批人规则在真实组织架构下走通一单
- 关键公式、联动在移动端与 PC 端各测一单
- OpenAPI 调用方使用生产环境 AppKey 与白名单
开发改完了，业务方说「还是老样子」
90% 是未发布或缓存
- 应用编辑态右上角确认「有未发布变更」提示，执行发布并填写变更说明
- 让业务方完全退出宜搭重新进入，或钉钉端清除应用缓存
- 对比「发布记录」时间戳与业务反馈时间，确认是否看错应用（测试应用 vs 生产应用）
发布后流程实例报错 / 字段缺失
删除字段或改字段类型后，进行中实例可能不兼容。发布前评估在途单量；重大结构变更选业务低峰期；必要时保留旧版流程处理在途，新版仅对新单生效（按官方版本策略操作）。
需要回滚到上一版本
在「发布记录」查看历史版本，按官方支持的范围回滚表单/流程配置（并非所有组件都支持一键回滚）。回滚前导出当前配置备份；通知业务暂停提交；回滚后回归测试核心路径再开放。
典型场景演练（端到端 SOP）
以下三个场景来自真实交付项目中的高频工单，按时间顺序操作可在 15–30 分钟内闭环。
场景 A：采购单提交后，采购经理在数据管理里「搜不到」
第 1 步 · 确认是不是权限问题（3 分钟）
用提交人账号登录 → 数据管理能否看到？若提交人可见、经理不可见 → 数据权限组问题。
第 2 步 · 查经理角色数据范围（5 分钟）
应用设置 → 成员与权限 → 经理所在角色 → 数据权限：若设为「本部门」而提交人跨部门，则经理看不到。改为「全部数据」或按「自定义条件」包含相关部门。
第 3 步 · 排除流程与筛选（5 分钟）
重置列表筛选；查「待我处理」是否卡在审批中；查智能助手Pro 是否将状态改为「草稿」导致被默认视图过滤。
结论判定：提交人可见 + 经理不可见 = 调数据权限；双方都不可见 = 查流程状态或自动化；仅管理员不可见 = 正常，检查是否用错账号。
场景 B：报销流程卡在「财务审核」超过 48 小时
第 1 步 · 看流程图待处理人（2 分钟）
实例详情 → 流程图：财务节点显示待处理人是谁？若为空 → 审批人规则失效（主管链断裂）。
第 2 步 · 核实审批人钉钉状态（5 分钟）
在钉钉通讯录确认该员工在岗、账号激活；是否开启审批委托把单转给代理人但未处理。
第 3 步 · 管理员运维（5 分钟）
流程运维 → 转交给在岗财务 B；或退回发起人补材料。同步检查该节点是否误设为「会签」导致一人未批全员卡住。
长期修复：财务节点改用「财务角色组」固定审批人 + 配置 24h 超时提醒与转交规则。
场景 C：OpenAPI 写入成功，但智能助手Pro 未同步 ERP
第 1 步 · 确认触发源（3 分钟）
智能助手Pro 若触发条件为「表单新增」，API 写入默认可能不触发（视版本与配置）。查运行日志该时间点是否有记录。
第 2 步 · 改触发策略（10 分钟）
方案一：API 写完后由中间服务再调一次「修改标记字段」触发自动化；方案二：改为定时任务批量同步未推送记录；方案三：直接用连接器 / 自定义 API 节点替代 Pro。
第 3 步 · 对账与幂等（10 分钟）
增加「同步状态」字段（待同步/已同步/失败）；失败写入日志表；ERP 侧用业务单号做幂等，避免重复推送。
根因归纳：集成问题先画数据流图（谁写主表、谁触发、谁回调），再选触发方式，避免假设「写了表就会自动跑 Pro」。
问题仍未解决？
官方渠道与算数科技实施团队均可协助——复杂集成、性能治理建议优先找有项目上下文的实施顾问。
宜搭官方：7×12 在线客服（企业版含专属客户经理）· 算数科技：18016313342（微信同号）