报错速查
跑不起来的时候先来这里：按症状找到所在的域，再照着原因与解法一条条排查；每条解法旁的「详见」会链到对应的速查页或课节去看细节。
怎么用这张表：先说清"你看到了什么"（不是"报了什么错"），在下面 6 个域里找到最接近的一行，照"解法"列从最省事的动作开始试；改完还不行，再点"详见"去对应速查页或课节看原理。本页是跨场景总表，只收通用意象的症状（"点按钮没反应""表格里的数没变"），不收具体报错文案——命令的完整属性、参数与示例在各自速查页里。
排查的通用顺序：先确认环境（文件在不在、账号能不能登、目标软件开没开）→ 再看代码（路径、类型、下标、循环）→ 最后才怀疑客户端。八成问题在前两步就解决了。
一、网页与元素
| 症状 | 原因 | 解法 | 详见 |
|---|---|---|---|
| 流程停在某一步不动了，说找不到那个东西 | 元素特征里勾了会变的属性（如随记录变化的文字、序号） | 把易变的属性取消勾选，或改用通配符 *；改完用「校验目标」确认还能找到 |
网页自动化速查 |
| 没报错，但明显点到了隔壁那个（清单里全是同一种行） | 兄弟元素特征雷同，流程照样往下跑 | 用 UI 分析器看父子/兄弟关系，给目标补回有区分度的属性，或改用父/子元素做锚点 | 网页自动化速查 |
| 点了按钮，页面状态没变；或点不动 | 元素还没出现、被遮挡、没滚到可视区 | 先用「等待元素」等它显示/可点，再执行「点击目标」；别用大段固定延时顶替等待 | 网页自动化速查 |
| 刚进页面就读文字，读回来是空的 | 页面还没加载完就去取值了 | 取之前加一道门禁：「判断元素是否存在」为真才继续，或直接用「等待元素」等它出现 | 网页自动化速查 |
| 这个网站根本选不到元素 / 取不到控件 | 站点跨域、元素在 iframe 里，或只支持 IE | 优先用内置的来也浏览器（可跨域选元素、可调页面内 JS）；iframe 内的元素在 UI 分析器可视化树里定位；只支持 IE 的站点用 启动新的浏览器 选 IE |
网页自动化速查 |
二、Excel 与数据
| 症状 | 原因 | 解法 | 详见 |
|---|---|---|---|
| 流程跑完了，表格里的数一点没变 | 写入时「立即保存」选了否，又没调用保存命令 | 三选一：写入时选「立即保存=是」；或流程结尾加 保存Excel；或 关闭Excel工作簿 的「立即保存」设为是 |
Excel 命令速查 |
| 数据写歪了、写不进去，或只写进去一部分 | 写入范围与数据的形状不一致 | 写一行用一维数组、写一片区域用二维数组；写入前用 创建多维数组 把数据摆成目标形状 |
Excel 命令速查 |
| 读到的数据从别的工作表 / 别的行开始 | 工作表整数编号从 0 起，单元格 [行,列] 从 1 起，两种口径混用 |
全流程统一一种写法：要么全用整数（工作表 0、单元格 [1,1]），要么全用字符串（"Sheet1"、"A1"） |
Excel 命令速查 |
| 第一次能跑，第二次就打不开或写不进这个文件 | 上一轮忘了 关闭Excel工作簿，后台 Excel 还占着；或文件正被手工打开的窗口锁住 |
只要写了 打开Excel，流程末尾就配一条 关闭Excel工作簿；跑之前先关掉手工打开的表格 |
第 7 课 · Excel 自动化 |
| 读回来的东西没法当数组用 / 拿到的是一整块文本 | 命令的输出类型与后续用法对不上 | 读一个格子用 读取单元格（输出随内容为数值或字符串）；读一片用 读取区域（输出二维数组），并把「输出到」声明成后续要用的类型 |
Excel 命令速查 |
三、Word 与邮件
| 症状 | 原因 | 解法 | 详见 |
|---|---|---|---|
| 另存出来的文件格式不对 / 双击打不开 | 文档另存为 只给了目录或漏了扩展名 |
路径里带完整文件名与扩展名（如 .docx）；拿不准当前文档在哪就先 获取文档路径 核对 |
Word 命令速查 |
生成的文档里模板标记原样留着（如 $姓名$） |
模板里的标记与代码里写的字符串不完全一致（空格、全半角、中文标点） | 用标记法逐字替换：查找文本后设置光标位置（相对位置选「选中文本」）+ 写入文字；标记不用行号定位，绕开隐藏格式导致的偏位 |
Word 命令速查 |
| 邮件发不出去 / 一连上就失败 | 登录密码填了邮箱原密码，或服务器、端口、SSL 组合不对 | 密码填授权码而不是原密码；端口按协议配（SMTP 465、POP3 995、IMAP 993，对应开启 SSL）；先用 连接邮箱 单独试通再接后续命令 |
Email 命令速查 |
| 附件发出去是空的 / 对方收不到附件 | 附件路径的基准目录不是你以为的那个 | 相对路径写 @res"文件名"（流程文件夹下的 res/）；或先 获取文档路径 拼出绝对路径再填 |
Email 命令速查 |
| 想群发，结果只收到一封 / 收件人只剩一个 | 多个收件人的写法不符合属性要求 | 把多个地址拼成一个字符串填进「收件人」属性，不要重复填同一个属性名；链路没验证过之前先只发一封 | Email 命令速查 |
四、流程逻辑与变量
| 症状 | 原因 | 解法 | 详见 |
|---|---|---|---|
| 金额算出来是一串数字，或者直接是 0 | 变量是字符串型，字符串拼接用 &，不是 + |
参与运算前先 转为整数数据 / 转为浮点数据；只在真要拼文字时用 &。数字常带千分位或单位，先清洗再算 |
BotScript 变量与类型速查 |
| 取某一条数据时跳出循环 / 取到空 | 数组下标从 0 起，长度 N 的最大下标是 N−1 | 手写循环时结束值写 长度 - 1；或者干脆用 For Each 值 In 数组 ... Next，不必自己管下标 |
第 6 课 · 数组与字典 |
| 按名字取数取到空 / 提示取不到这个键 | 字典的键是字符串，键名拼写与写入处不一致 | 键名与赋值处逐字对齐（含大小写、空格）；不确定时先 For Each 键, 值 In 字典 把实际键打出来看 |
第 6 课 · 数组与字典 |
| 条件判断不起作用，走进或绕开了该走的分支 | = 单独成句是赋值，写在表达式里才是判断相等 |
条件写成表达式（如 If 金额 <> 0）；If 后不写 Then，语句块以 End If 收尾 |
BotScript 变量与类型速查 |
| 流程转不停 / 一圈原地打转 | 手写计数的循环忘了让计数器前进，或终止条件写反了 | 能用 For ... Next 就别手写计数（Next 自动步进）；确实要用 Do 时，循环体里必须 i = i + 1，并留好 Break / Exit 出口 |
第 5 课 · 循环 |
五、运行环境与客户端
| 症状 | 原因 | 解法 | 详见 |
|---|---|---|---|
| 在自己电脑上能跑，交给别人或在另一台机器上就失败 | 开发环境与运行环境不一致（同系统、同浏览器是最敏感的） | 让执行端与开发端保持同系统、同浏览器；元素特征在 Chrome 与 IE 上可能完全不同，别跨浏览器复用 | 平台地图 |
| 想让它定时自己跑，社区版做不到 | 机器人指挥官社区版不提供，社区版只能发布到社区版的指挥官与机器人商城 | 社区版就在 APA Creator 里本地试跑、手动触发；要"定时 + 无人值守"需要执行端与指挥官的配合 | 平台地图 |
| 同一个元素在别的流程块里找不到 / 界面库像是空的 | 界面库在流程内各流程块之间共享，流程之间不共享 | 用 UI 分析器「保存到界面库」把它固化下来再复用；跨流程要么各选一次，要么用相对稳定的特征重选 | 第 2 课 · 界面 |
| 在 Creator 里调试能过，发布出去就跑不通 | 调试态悄悄依赖了本机现成条件：已登录的浏览器、已装好的客户端、已打开的文件 | 把对环境的依赖显式写进流程（自己 启动新的浏览器、自己关掉上一轮遗留的文档）；发布前在一台干净机器上完整跑一遍 |
第 2 课 · 界面 |
| 同一台机器上多个实例互相干扰 / 抢同一个文件或浏览器 | 多个机器人同时操作同一份资源 | 同一执行端上让任务串行跑，或给每个实例分配独立的账号、目录与浏览器会话 | 平台地图 |
六、文件与编码
| 症状 | 原因 | 解法 | 详见 |
|---|---|---|---|
| 文件明明放在流程文件夹里，却说找不到 | 相对路径的基准是 res/；Windows 还可能把扩展名藏起来 |
统一用 @res"文件名"（流程文件夹 / res/ / 文件名）；核对 res 的拼写与大小写，以及文件是不是叫「名字.xlsx」而不是「名字」 |
第 7 课 · Excel 自动化 |
| 拼出来的保存路径少一段 / 文件名被判为非法 | 目录串末尾少了反斜杠；姓名、单号里混进了 \ / : * ? " < > | |
拼路径时让目录串末尾带上 \ 再接文件名；对来自业务数据的名字先做非法字符清洗 |
第 12 课 · 对账机器人 |
| 中文写进文件、或读出来是乱码；CSV 用 Excel 打开全是乱码 | 写入与读取用的编码不一致，Excel 也不认无 BOM 的 UTF-8 | 文本一律存成 UTF-8 带 BOM（站内练习数据就是这么给的，Excel 直开不乱码）；尽量用 打开Excel / 打开文档 这类按格式打开的命令，让客户端自己识别 |
第 12 课 · 对账机器人 |
| CSV 里一列被拆成好几列，或引号包住的整段被切开 | 分隔符、转义规则与实际文件不一致 | 读 CSV 时显式指定分隔符为逗号；含逗号、换行或引号的字段用双引号包住；导出后先数一遍行数与列数再入库 | 第 12 课 · 对账机器人 |
| 文件改不动 / 下次打不开；目录里堆着一堆中间文件 | 文件被锁（还开着的 Excel/WPS，或上一轮忘了关闭），中间产物没人清 | 跑之前关掉手工打开的文件，确认流程里有 关闭Excel工作簿 / 关闭文档；把 res/ 作输入目录、输出目录单独建，只留最终文件 |
第 7 课 · Excel 自动化 |
什么时候该跳出这张表：本页收的是"通用意象"的症状。一旦你需要确认某条命令到底有哪些属性、某个参数怎么填、某个返回值是什么类型——去官方命令手册与开发者指南按软件名或命令名搜；概念层面的疑问（流程/流程块/命令/属性的关系、语法规则、平台组件分工）站内已经写全，优先在语法速查与平台地图里查。第三方资料与站内冲突时，以站内为准，再以官方文档为准。