简介：Katalon Recorder 脚本录制工具包面向需要快速上手 Web 自动化测试的开发者与测试人员，尤其适合刚接触 Selenium、希望降低脚本编写门槛的初中级使用者。它能把浏览器操作直接转化为可执行的自动化脚本，缓解手工回归测试重复劳动多、录制与回放流程搭建慢的问题。压缩包共 4 个文件，含 2 个 crx 扩展与 2 个 html 说明文档，整体约 3.95MB：crx 为可直接拖入 Chrome 扩展管理页安装的录制插件，html 承载安装指引与使用说明，便于对照完成环境准备。目前已有 1522 人学习下载。读者可获得一套完整的浏览器端录制—回放工作流：录制时自动识别页面元素并生成测试步骤，录制后可在内置编辑器中调整脚本、补充断言与循环等逻辑以覆盖更复杂的场景，遇到元素定位或回放异常时，也能借助说明文档与社区教程找到排错方向。

1. 装前先对齐版本：Katalon Recorder 扩展版和桌面版别混着来

Katalon Recorder 这类脚本录制工具，很多人的第一印象是「一个浏览器插件，装上点红点就能录」，真到动手那天才发现完全不是这么回事。做自动化回归的团队几乎绕不开它：手工用例攒了几百条，想低成本转成可重复执行的脚本，录制是不写代码的唯一入口。可装错了版本形态，扩展在浏览器工具栏里是灰的，录制按钮点下去没反应，导出的脚本一行都跑不通，排查两小时才发现装的是旧架构的包。

这套东西适合两类人：刚接手自动化、想先把一条流程跑通的新手，和要把手工用例批量转成脚本、还得塞进持续集成流水线的熟手。第 1 章不讲命令，先把「装哪种」这件事定下来，后面所有步骤才有意义。

2. 环境先列清：Katalon Recorder 装前要对的浏览器、JDK 和驱动版本

2.1 三样东西的版本关系，先记录再动手

接手一台新机器，我一般不会先解压，而是先跑四条命令把宿主环境记录下来。原因很实际：Katalon Recorder 的坑十有八九不是它自己的，而是浏览器主版本、驱动主版本、运行时版本这三者对不上。扩展跑在浏览器里，浏览器主版本决定了三件事——能不能加载这个扩展清单版本、录制用的页面事件接口是否还在、导出的 WebDriver 代码该配哪个驱动。这三件事任意一件出偏差，表现都是「录得到、放不出来」或者「放得出来、导出跑不了」。

# 把宿主环境的版本一次性打出来，存进自己的部署笔记备查 # 1) 浏览器主版本：也可以在地址栏打开 chrome://version 直接看 export CHROME_BIN="/usr/bin/chromium" # 按自己机器上的实际路径改，macOS 指向 .app 内部的可执行文件 "$CHROME_BIN" --version # 2) JDK：只导出 Katalon Studio 工程和 Robot Framework 用例时才需要 java -version 2>&1 | head -n 1 # 3) 驱动：主版本号要跟上面的浏览器主版本完全一致 chromedriver --version 2>/dev/null || echo "chromedriver 尚未安装" # 4) Python 运行时：导出 Python 脚本才用得上 python3 -V

这段命令没有任何副作用，纯粹是为了留证据。后面任何一步翻车，第一步都是拿这几行输出跟报错信息对一遍，比盲目重装快得多。参数上唯一要注意的是CHROME_BIN这个变量，它只是个普通环境变量名，改成BROWSER_PATH之类也行，关键是别在脚本里写死平台路径——同一套脚本要在一台 Linux 构建机和一台 macOS 开发机上跑，路径写死是必踩的坑。

java -version的输出走的是标准错误，所以要2>&1才能被head接住，这个细节很多人第一次写检查脚本时会漏掉，导致检查永远显示「未安装 JDK」。chromedriver --version后面跟了||兜底，是因为很多机器上驱动不是全局安装的，而是随项目放在drivers/目录里，没装就该老实打印「尚未安装」，而不是让整段脚本中断。

有一点要提前说清楚：Katalon Recorder 的浏览器扩展形态本身不需要 JDK。很多人看到教程里让装 Java 就顺手装了，其实只有在你要把录制的用例导出成 Katalon Studio 工程、导出 Robot Framework 用例、或者在流水线里跑这几种场景下，JDK 才是硬依赖。纯录制加导出 Selenium WebDriver 代码的路径，Python 加 Selenium 就够了。

2.2 三种安装路径的取舍：商店装、离线目录装、桌面版装

同一个工具，落地方式有三种，选错了后面全是麻烦。

团队协作场景我基本只推第二种。原因很直白：录制出来的用例要进版本库，要给别人复现，如果 A 的扩展是商店自动更新到的新版、B 的是三个月前的旧版，同一份.side文件在两个人机器上回放结果不一致，这种事查起来非常消耗精力。离线目录加载把版本钉死在一个固定路径下，包跟着项目走，谁拉下来都是同一份。

商店安装适合快速验证「这东西能不能解决我的问题」，但别把它当成长期方案。桌面版适合回放时间长的场景——录制器挂在浏览器面板里，浏览器一关回放就断了，桌面版是独立进程，稳定得多；代价是多一套安装包，而且要单独确认它内置的驱动版本。

2.3 安装前的清理和目录规约

在解压之前，先做两件清理。第一，禁用机器上其它同类录制扩展，比如老版本的同类录制器。多个录制器同时监听页面事件，表现是点击一次在用例表里冒出两三条重复命令，或者干脆一条都没有——这不是玄学，就是事件被抢了。第二，如果之前装过旧版 Katalon Recorder，先在扩展管理页面移除，别直接覆盖加载，残留的旧配置会让新版本的默认超时、定位器顺序全是上一版的。

目录我统一按下面这个结构放，好处是后面所有命令都能用固定路径，不用每次cd到解压目录里找半天：

# 建立统一的工具目录，扩展、桌面版安装包、驱动、导出的工程分开放 mkdir -p "$HOME/tools/katalon-recorder"/{extension,desktop,drivers,projects} # 解压到临时目录再挑，避免压缩包内多套一层同名文件夹时路径写错 unzip -q "Katalon Recorder-脚本录制工具.zip" -d "$HOME/tools/katalon-recorder/_unpack" # 确认解压结果的层级，重点看 extension 目录下是不是直接躺着 manifest.json find "$HOME/tools/katalon-recorder/_unpack" -maxdepth 3 -name "manifest.json"

-q是安静模式，解压几十上百个文件时不会刷屏；-d指定目标目录，这个参数一定要写，否则压缩包会散落在当前工作目录里。压缩包名字带空格和中文，所以必须用引号包住，这一步在 Windows 的 Git Bash 里尤其容易出问题。find那行的作用是提前定位manifest.json的位置——浏览器加载未打包扩展时，你选中的目录必须直接包含 manifest.json，多套一层父目录就会报清单文件缺失，这是新手最常卡住的地方，放到第 5 章还会细说。

另外提醒一句，Windows 上用系统自带解压工具处理含中文文件名的压缩包，偶尔会出现文件名乱码，导致后续路径对不上。遇到这种情况换 7-Zip 或者命令行unzip重新解一遍，别在乱码目录上硬改。

3. 安装实操：Katalon Recorder 离线包解压、扩展加载与首次启动

3.1 解压后的目录结构核对

包解出来之后，先别急着往浏览器里加载，花一分钟把目录用途对一遍。这类离线包通常按安装方式分了子目录：扩展目录是给浏览器加载用的，桌面版目录里放的是各平台的安装程序，驱动目录里放的是对应版本的浏览器驱动，另外还有一份快速上手说明。不同版本的分法可能略有出入，但manifest.json一定在扩展目录的最外层。

# 用一行 Python 把扩展清单的关键字段读出来，确认版本形态对不对 python3 - <<'PY' import json, pathlib p = pathlib.Path.home() / "tools/katalon-recorder/extension/manifest.json" m = json.loads(p.read_text(encoding="utf-8")) print("name :", m.get("name")) print("version :", m.get("version")) print("manifest_version:", m.get("manifest_version")) print("permissions :", ",".join(m.get("permissions", []))[:120]) PY

这段脚本读的是扩展清单本身，输出里最该盯的是manifest_version这一项。它决定了当前浏览器还认不认这个扩展：老版本清单在新版浏览器上会被直接拒绝加载，卡片变灰、开关打不开，报错通常只说「此扩展程序可能已损坏」之类，不会明说版本问题。把这一行先记下来，后面出问题能省一大圈。

permissions那行做截断输出，是为了快速确认扩展有没有拿到页面读写、标签页访问这类权限。少了某个权限，表现是能打开面板但录不到页面动作，跟装错版本的症状很像，容易误判。

3.2 浏览器开发者模式加载离线扩展

标准流程走一遍，五步，每一步都有个容易漏的点。

1. 地址栏进扩展管理页，打开右上角「开发者模式」开关。不开这个开关，加载按钮根本不出现。
2. 点「加载已解压的扩展程序」，在文件选择框里选中extension目录——注意是包含 manifest.json 的那一层，不是它的父目录。
3. 加载成功后，卡片上会出现扩展 ID 和一串版本号，把这两个值抄进部署笔记。
4. 点工具栏的拼图图标，把这个扩展固定到工具栏，否则录制入口藏得太深，每次都要翻两层菜单。
5. 关掉开发者模式开关前先想一下：关掉之后，用「加载已解压」方式装进来的扩展可能会被停用。日常开发建议保持开启。

企业环境里如果加载按钮是灰的、提示「由贵组织管理」，那是浏览器策略在生效，个人层面改不动，需要找管策略的人把扩展 ID 加进白名单。这种情况不用反复重装，装十遍也是一样的结果。

3.3 用命令行带扩展起一个独立实例

日常浏览器上装一堆扩展，录制时最怕的就是别的扩展往页面里注入脚本，干扰定位。我的做法是给录制器单独开一个浏览器配置目录，启动时只加载这一个扩展：

# 独立 profile + 只加载录制扩展，避免其它扩展干扰页面事件 PROFILE_DIR="$HOME/.katalon-recorder-profile" EXT_DIR="$HOME/tools/katalon-recorder/extension" "$CHROME_BIN" \ --user-data-dir="$PROFILE_DIR" \ --load-extension="$EXT_DIR" \ --disable-extensions-except="$EXT_DIR" \ --no-first-run \ --no-default-browser-check \ about:blank

--user-data-dir指定独立的用户配置目录，登录态、书签、扩展配置全在这个目录里，跟日常浏览器完全隔离，删掉这个目录就等于重置录制环境。--load-extension加载未打包扩展，--disable-extensions-except反过来屏蔽其它所有扩展，只留指定的这一个——这两个参数配合使用，才能做到「干净实例」。后两个--no-*是跳过首次运行引导和默认浏览器检查，在构建机上跑的时候不加会被弹窗卡住。

注意：浏览器版本迭代过程中，命令行加载未打包扩展的能力被收紧过，部分版本上--load-extension会被静默忽略，扩展没加载但没有任何报错。遇到这种情况别死磕命令行，退回 3.2 的手动加载流程操作一次，配置目录会记住这个扩展，之后用同一个--user-data-dir启动就能带上它。

3.4 首次启动后的基础设置

扩展面板第一次打开是空的，先调四项再录第一条。

这四项里最容易被忽略的是回放速度。很多人为了让用例跑得快，把速度拉到最高，本地全绿，一上流水线就大片超时。录制回放的价值在于稳定复现，不在于快，速度留在中速，把不稳的等待改成显式等待，比调速度有用得多。

4. 录制配置：定位器、超时和导出格式三个参数怎么定

4.1 定位器优先级：把易变的排到后面

录制器生成的每条命令都带一个定位表达式，写进表格的 target 列。默认情况下它会同时尝试多种定位策略，按顺序挑第一个能唯一命中的。问题在于，很多页面的 id 是框架自动生成的，带一串随机字符，今天录的明天就变了；有些列表页的 XPath 带位置下标，页面上多一条数据整个表达式就错位。

我的做法是进设置面板，把定位器构建顺序调成下面这样，并且把带位置下标的 XPath 和 DOM 路径这两项直接取消勾选：

调完顺序不代表就完事了。录制结束后一定要把用例表从头到尾扫一遍，凡是 target 列里出现连续数字、哈希串、div[3]/div[2]这种结构的，当场改成稳定定位。这一步花五分钟，能省掉后面反复回放失败的两小时。表格里的 target 是可以直接双击编辑的，改完记得保存用例。

4.2 三个时间参数别混着用

录制器里跟时间相关的参数不止一个，混用是回放不稳定的主因。

真正有效的做法不是全局调大，而是在关键节点插显式等待。下面是一段录制后整理过的命令序列，能看出等待该加在哪：

waitForElementVisible的 value 是该条命令自己的等待上限，跟全局默认超时是两回事。加在open之后，是因为单页应用路由切换时 DOM 是异步渲染的，页面加载完成不代表元素已经在了；加在click之后，是因为登录请求有网络往返，跳转时间不可控。这两处加上显式等待，全局默认超时才有条件调回 30000，整体反而更快。

assertText放在最后，是用来做结果校验的。只录制操作不录制断言，回放永远是绿的，这种用例没有任何价值——它只能证明流程能点通，证明不了结果对不对。

4.3 导出格式与目标工程对接

录制只是中间产物，最终要落到能进版本库、能进流水线的代码上。导出选项一般有这几类：

选择的判断标准只有一条：这套用例最终跑在哪个流水线里。别为了导出方便选一个团队根本不维护的技术栈，导出来的代码没人接，等于白录。没有流水线、只想先把手工用例存档的，导.side就够，它结构简单，将来换工具也迁得动。

4.4 用 .side 文件做用例版本管理

.side本质是个 JSON 文件，用 git 管理它，diff 出来的内容是可读的。这一点比导出成脚本更有优势——脚本里混着大量框架代码，改一个定位器 diff 出一大片，评审时根本看不出改了什么。

# 统计一个 .side 文件里的用例条数和命令条数，方便衡量改动规模 jq '.tests | length' projects/login.side jq '[.tests[].commands[]] | length' projects/login.side # 对比两次提交之间到底改了哪些定位器，比看脚本 diff 清爽得多 git diff HEAD~1 -- projects/login.side | grep -E '^\+.*"(target|command)"'

jq这两个表达式分别取用例数组长度和所有命令的扁平长度，第一个数字是用例数，第二个是命令总数。用例改动评审时看这两个数就能判断规模，涨了几十条命令的提交值得细看。第二条命令过滤出新增行里的命令和定位表达式，定位器被批量替换这类改动一眼就能发现。

文件命名建议按「模块_场景_序号」来，比如login_正常登录_01.side、order_取消订单_02.side。别用日期命名，用例是长期资产，日期只反映录制时间，跟内容无关，检索时反而碍事。同一目录下再放一份 README 写清楚每条用例的前置数据，半年后来接手的人会省很多事。

5. 排查避坑：Katalon Recorder 装不上、录不到、回放全红的 5 个坑

5.1 加载扩展报「清单文件缺失或不可读」

现象：在扩展管理页选中目录后，弹窗提示清单文件缺失或不可读，卡片加载不出来。

原因：选中的目录不是包含 manifest.json 的那一层。压缩包解压后常常多套一层同名文件夹，或者清单文件在extension/子目录里，用户顺手选了最外层。另一种可能是解压不完整，清单文件被截断成零字节。

解决：先find定位清单文件的确切路径，再回到文件选择框选它所在的目录。如果是零字节，删掉重解压。这个问题跟浏览器版本无关，也不涉及权限，纯粹是路径选错，但报错文案完全看不出来，所以排第一位。

5.2 扩展装上了，卡片显示「已停用」

现象：加载过程没报错，但卡片是灰的，开关打不开，提示可能已损坏或被策略停用。

原因：三种可能。扩展清单版本过旧，当前浏览器已经不再加载这个版本；浏览器处于无痕模式或某个受限配置下；企业策略把未打包扩展统一禁用了。

解决：先看 3.1 打出来的manifest_version，太旧就换新版安装包；再换正常窗口试一次；最后进策略页确认有没有管理员策略在管。前两种自己能解决，第三种只能走白名单流程，别浪费时间反复重装。

5.3 点了录制，页面操作一条都记不下来

现象：录制按钮是开着的，页面上点输入框、点按钮，用例表里一条命令都不新增。

原因：最常见的是录制开关只开了面板、没绑定到目标标签页——录制器只对当前激活的那个标签页生效，切到新开的标签页后需要重新点一次录制。其次是页面主体在 iframe 里，或者用了 Shadow DOM，录制器在外层文档上监听事件，进不到内层。第三是另一个同类录制扩展在抢事件。

解决：确认录制器绑定的是你要操作的那个标签页；iframe 场景下先录一个切换框架的命令，再录内层操作；Shadow DOM 里的元素基本录不到，直接手工在表格里补一条 CSS 定位的命令更快；最后禁用其它同类扩展再试。

5.4 回放报元素不可交互或直接超时

现象：回放到某一步红掉，报元素不可交互、元素找不到、点击被拦截之类。

原因：定位表达式命中了隐藏元素。响应式页面为了适配不同屏幕，会同时渲染桌面版和移动版的节点，同名元素有两个，一个display:none。按位置生成的 XPath 尤其容易命中隐藏节点。还有一种情况是元素在视口外，点击前需要滚动。

解决：把定位器从位置 XPath 改成稳定的 id 或 CSS，去掉名称重复的节点；在点击命令前插一条滚动到元素的命令；确认等待命令加在了正确的位置。这三步能解决九成以上的回放失败。

5.5 导出的 Python 脚本本机跑不起来

现象：导出的脚本在录制器里能跑，脱离录制器执行报驱动版本不匹配、会话创建失败，或者提示某个方法不存在。

原因：驱动主版本和浏览器主版本不一致；虚拟环境里装的是旧版 selenium，API 名字对不上；导出脚本里硬编码了本机路径。

解决：把 selenium 升到 4.x 系列，新版本自带驱动管理，不用手工下驱动；确实要手工管驱动的，用 2.1 里那条chromedriver --version跟浏览器主版本逐位对齐主版本号；导出脚本里的绝对路径改成相对路径或环境变量。

这五条里，前三条属于「装」的阶段，后两条属于「用」的阶段。新手最容易在第一条上卡住，熟手更容易栽在第五条——本地环境早就配好了，换台机器就崩。把这几条抄进部署文档，比事后靠回忆强。

6. 装完验证：一条用例走完录制、回放和脚本独立执行

装完不代表能用。我的验收标准是四个动作全绿，缺一个都不算装完。

第三第四项很多人直接跳过，结果交付给流水线时才发现导出的脚本根本跑不起来。独立执行这一步给个最小可复现的做法：

# 脱离录制器验证：用隔离环境 + 无头模式跑一遍导出的用例 python3 -m venv .venv source .venv/bin/activate pip install "selenium>=4.11" pytest # 无头模式下跑，能过说明不依赖图形界面，可以直接进流水线 pytest -q tests/test_login.py --tb=short

虚拟环境是为了把依赖钉在当前项目里，避免污染系统 Python。selenium>=4.11这个下限是必须要的，4.6 之后自带驱动管理，选中版本时不用再手工对齐驱动。--tb=short缩短失败堆栈，排错时先看最后几行就够了。无头模式一定要试，很多脚本在带界面的浏览器里跑得好好的，一进构建机就挂，原因通常是无头模式下窗口尺寸不同，触发了响应式布局切换到移动版节点，之前录制的定位器全落空。真遇到了，在启动参数里固定一个窗口尺寸就能绕过去。

还有一个容易被忽略的验证点：把导出的用例连续跑三遍，三遍全绿才算通过。只跑一遍的通过是偶然，跑三遍才说明等待策略是真的有效，而不是刚好那次网络快。我第一次部署时就是只跑了一遍，看着全绿就交付了，第二天流水线上一半用例红掉，回头查发现全是等待没加够，页面渲染慢一点就崩。从那以后我每次装完 Katalon Recorder，都会强制走一遍「录一条 → 回放三遍 → 导一条 → 无头跑一条」这个闭环，四个动作任何一个红，都不算装完。

这套流程走下来大概二十分钟，比起事后在流水线上排查几十条飘忽不定的失败用例，这二十分钟花得值。希望帮到你。

本文还有配套的精品资源，点击获取