站点配置

目标

管理站点的高级配置，包括加密 URL、脚本、模拟设备、代理、请求/响应头记录、页面控制和访问行为。

前置条件

• 已创建目标站点。
• 准备发布脚本前，应先测试站点。

操作步骤

1. 进入“站点管理 > 站点列表”。
2. 找到目标站点，点击配置。
3. 按需启用加密 URL，避免用户前端直接显示源站地址。
4. 配置浏览器模拟、代理、请求头、响应头、页面控制和脚本。
5. 保存站点配置。
6. 使用测试账号访问目标站点，验证打开、登录、跳转、接口数据和 SSE 事件处理是否符合预期。
7. 如需按帐户分类定制行为，返回站点列表并进入“帐户分类配置”。

配置项说明

配置项	用途	注意事项
加密 URL	隐藏用户前端展示的源站地址	不能替代目标站点自身认证
浏览器模拟	调整浏览器品牌、移动设备模型、时区等识别信息	修改后需重新验证目标站点兼容性
代理设置	为该站点配置直连、系统代理、PAC 或固定代理服务器	代理错误会导致站点无法打开或登录异常
请求头	记录指定请求头，供页面脚本通过 api.header(name, true) 读取	只记录已配置且实际经过远程浏览器的请求头
响应头	记录指定响应头，供页面脚本通过 api.header(name, false) 读取	响应头名称读取时会转为小写
页面脚本	处理 DOM、表单、按钮、页面跳转和页面增强	应限制匹配 URL，避免误作用
SSE 脚本	改写服务端事件流数据	适合高级场景，建议先测试
普通接口拦截脚本	改写非 SSE 接口响应 body	脚本必须返回新的响应 body 字符串
页面控制	按 URL 和选择器隐藏或删除页面元素	目标站点改版后选择器可能失效
帐户分类配置	为不同帐户分类设置差异化登录逻辑	与站点浏览器账号配合使用

脚本配置

站点配置页的“脚本配置”用于为目标站点添加一组脚本规则。每条脚本根据匹配 URL 和脚本类型，在远程浏览器访问目标站点时执行。

字段	类型	说明
name	string	脚本名称，建议使用“站点-用途-版本”格式，例如 crm-login-v1。
url	string	匹配 URL。为空时通常按 * 理解，建议生产环境尽量写得更精确。
pageScript	boolean	是否为页面脚本。开启后脚本在页面环境中执行，可使用 window.api。
sseScript	boolean	是否为 SSE 拦截脚本。只有 pageScript = false 时显示和生效。
selector	string	页面脚本的执行条件。填写后，只有页面能匹配该 CSS 或 XPath 选择器时才执行脚本。
content	string	JavaScript 脚本内容。不同脚本类型的入参和返回值不同。

页面脚本

当 pageScript = true 时，脚本作为页面脚本运行，适合处理 DOM、表单、按钮点击、页面跳转、覆盖层、用户数据读写和页面增强。

运行行为：

1. 远程浏览器访问目标页面。
2. 系统在页面和可访问 iframe 中初始化 window.api。
3. 如果配置了 selector，只有选择器能匹配到元素时才执行脚本。
4. 脚本可以直接使用 api.config、api.user、api.dom、api.utils 和 api.header()。完整 API 见脚本 API 附录。

示例：等待元素出现后隐藏广告区域，并读取产品配置。

await api.utils.wait(
  () => !!api.dom.querySelector(document, '.main-panel'),
  10000,
  200
);

const envName = api.config.envName || 'default';
console.log('current env:', envName);

const banner = api.dom.querySelector(document, '.ad-banner');
if (banner) {
  banner.style.display = 'none';
}

SSE 脚本

当 pageScript = false 且 sseScript = true 时，脚本用于拦截 Server-Sent Events 数据。系统会包装页面中的 EventSource 和 fetch，对匹配 URL 且内容类型为 text/event-stream 的数据流进行处理。

脚本执行形式：

async (data) => {
  // content 中填写的脚本内容
}

入参	类型	说明
data	string	当前 SSE message 或流式 chunk 文本。

返回值必须是新的 SSE 文本。未返回字符串时，可能导致页面收到的数据异常。

示例：替换 SSE 数据中的文本。

return data.replace('old text', 'new text');

普通接口拦截脚本

当 pageScript = false 且 sseScript = false 时，脚本用于拦截普通接口响应。系统会匹配接口 URL，读取响应 body，并把 body 交给脚本改写。

脚本执行形式：

async (data, api, url) => {
  // content 中填写的脚本内容
}

入参	类型	说明
data	string	原始响应 body。
api	object	脚本 API，结构见脚本 API 附录。
url	string	当前被拦截的接口 URL。

返回值必须是新的响应 body 字符串。

示例：改写 JSON 接口响应。

const obj = JSON.parse(data);
obj.debug = true;
obj.fromScript = url.includes('/api/');
return JSON.stringify(obj);

匹配 URL 规则

url 字段支持以下规则：

写法	说明	示例
*	匹配全部 URL	*
regex:<表达式>	使用正则表达式匹配 URL	regex:/api/chat
exact:<完整URL>	精确匹配完整 URL	exact:https://example.com/api/user
script:<表达式>	把当前 URL 作为变量 url 执行表达式	script:url.includes('/api/')
普通字符串	判断目标 URL 是否以该字符串开头	https://example.com/api/

建议生产脚本尽量使用精确路径或稳定前缀，减少影响无关页面和接口的风险。

请求头与响应头

站点配置中的请求头和响应头用于记录指定 header，页面脚本可通过 api.header() 读取。完整参数见脚本 API 附录。

使用步骤：

1. 在“请求头”中添加需要记录的请求头名称，例如 authorization、cookie。
2. 在“响应头”中添加需要记录的响应头名称，例如 content-type、set-cookie。
3. 保存配置，并通过远程浏览器访问目标站点。
4. 在页面脚本中读取。

const authorization = await api.header('authorization', true);
const contentType = await api.header('content-type', false);

注意：

• Header 名称读取时会转为小写。
• 只有已配置并且实际经过远程浏览器的 header 才能读取。
• 响应头可能是字符串数组，脚本应兼容数组和空值。

选择器语法

脚本选择器和页面控制选择器支持 CSS 与 XPath。

写法	说明
.button.primary	CSS 选择器。
xpath://div[@id="app"]	XPath 选择器。
.dialog:p	返回匹配元素的父元素。
.dialog:p2	返回匹配元素向上两级的父元素。
.header:bottom	覆盖层边界方法中取目标元素下边界。
.sidebar:right	覆盖层边界方法中取目标元素右边界。

配置变更流程

1. 记录当前配置和脚本内容。
2. 在测试站点或测试账号上修改。
3. 验证打开、登录、跳转、退出、接口响应和 SSE 事件。
4. 检查页面控制规则是否隐藏或删除了正确元素。
5. 将配置同步到生产站点。
6. 通知相关用户重新进入站点验证。

结果验证

• 用户前端站点卡片按配置显示。
• 开启加密 URL 后，用户界面不直接展示源站 URL。
• 定制脚本在远程浏览器访问目标站点时按匹配规则生效。
• 页面脚本能正确读取配置、定位元素和处理页面行为。
• SSE 脚本只改写目标事件流，不影响普通接口。
• 普通接口拦截脚本能返回合法响应 body。
• 目标站点改版后，脚本和选择器仍能正常匹配。

常见问题

• 脚本应先在测试站点验证，再用于生产站点。
• 加密 URL 只影响前端展示和访问路径，不代表绕过目标站点自身安全策略。
• 页面脚本适合处理 DOM、表单和页面行为。
• SSE 脚本只适合处理服务端事件流，不应拿来处理普通 JSON 接口。
• 普通接口拦截脚本必须返回字符串，否则目标页面可能无法解析响应。
• 可用脚本 API 的完整参数和示例见脚本 API 附录。
• 帐户分类配置适合为同一站点的不同登录方式定义差异化行为。