ego-lite的js()自动IIFE包装机制详解：3大常见坑与浏览器自动化完整避坑指南-平芜编程栈

ego-lite的js()自动IIFE包装机制详解：3大常见坑与浏览器自动化完整避坑指南

【免费下载链接】ego-liteThe fastest browser for AI agents to run browser automation, built for sharing your logged-in browser state with your AI agents, like Codex or Claude Code, without disturbing you. Zero cost, zero config.项目地址: https://gitcode.com/GitHub_Trending/eg/ego-lite

ego-lite（ego-browser）是一款专为 AI Agent 打造的高速浏览器自动化工具，能把你已登录的浏览器状态安全共享给 Codex、Claude Code 等 AI 助手。它的脚本 API 中，js()是最常用的"页面内执行 JavaScript"方法——但很多人不知道：只要表达式里出现了顶层return，js()就会自动帮你把代码包进一个 IIFE（立即执行函数表达式）里。这个贴心的自动包装机制很强大，却也是新手最常踩坑的地方。本文带你 5 分钟看懂原理，并给出 3 个高频坑的完整避坑方案。

js() 是什么：一行代码在页面里跑 JS

在 ego-browser 的 heredoc 脚本里，js()本质上就是浏览器 CDP 协议中的Runtime.evaluate：你传一段字符串，它在当前页面执行并直接返回求值结果（不是 JSON 字符串）。

const count = await js(`document.querySelectorAll('article').length`)

问题来了：document.title这样的表达式可以直接求值，但下面这种带return的"函数体写法"直接执行会报SyntaxError: Illegal return statement：

// 在普通表达式位置，顶层 return 是非法的 return document.title

ego-lite 的解决方案是自动 IIFE 包装：检测到顶层return后，把你的代码自动改成：

(function(){ return document.title })()

这样既兼容了 Playwright / Puppeteer 用户习惯的写法，又不会破坏普通表达式。

包装判定逻辑：哪些 return 会触发自动包装？

判定代码非常精炼，位于 cdp-eval.ts：

if (hasReturnStatement(expression) && !expression.trim().startsWith("(")) { expression = `(function(){${expression}})()`; }

两个条件缺一不可：

条件	说明
① 存在顶层`return`	由专门的 hasReturnStatement() 状态机识别
② 表达式不以`(`开头	避免把你自己写的 IIFE 再包一层

hasReturnStatement()并不只是简单的字符串搜索，它用一个状态机逐字符扫描，正确处理了以下场景：

字符串里的return不算数："return 1"、'return x'、模板字符串都不会误判；
注释里的return不算数：// return 1和/* return 1 */会被跳过；
标识符里的 return 不算数：const returned = 1、returnCode这类变量名不会误触发。

这些细节在 cdp-eval.test.mjs 中有完整的自动化测试覆盖，你可以放心地写带字符串和注释的复杂表达式。

3 大常见坑：新手最常踩的 IIFE 包装陷阱

坑 1：嵌套回调里的 return "意外"触发包装

状态机扫描的是文本层面的return，它不感知函数边界。如果你的代码里某个回调（比如.map()、事件监听器）中写了return，也会触发自动包装：

// 回调里的 return 也会触发 IIFE 包装 const titles = await js(`[...document.querySelectorAll('h1')].map(el => { return el.innerText })`)

后果：包装本身通常不影响执行结果，但代码被悄悄改写后，出错时你看到的堆栈行号、表达式内容都会对不上，调试体验极差。

避坑方案：官方建议——复杂逻辑一律显式写成 IIFE，只 return 一次。以(开头的表达式会被判定条件 ② 拦截，绝不二次包装，行为完全可预期。官方技能文档 SKILL.md 给出的推荐写法：

const data = await js(String.raw`(() => { const items = [...document.querySelectorAll('article')] return items.map(el => ({ text: el.innerText, links: [...el.querySelectorAll('a')].map(a => a.href), })) })()`)

坑 2：以为传了函数或参数给 js()

js()只接受字符串（函数形式会被一次性警告并用.toString()序列化，闭包不会被捕获）。另外，字符串形式的第二个参数不是数据参数，而是遗留的 target id——用于附加到 iframe 等子目标后再执行。传对象参数会直接抛TypeError。

避坑方案：需要传参时，直接把值拼进表达式字符串，或改用一个自包含的 IIFE；要操作 iframe，才把 target id 作为第二个参数传入。

坑 3：返回值再套 JSON.parse，或正则反斜杠丢失

js()返回的是已求值的真实值（数字、数组、对象、甚至NaN/BigInt都能正确解码），千万不要再JSON.parse()一次；
在模板字符串里写正则时，\d会被提前转义成d，导致 IIFE 内正则失效。要么双写反斜杠\\d，要么直接给字符串加String.raw前缀。

最佳实践清单：让 IIFE 包装为你所用

✅ 推荐	❌ 避免
简单表达式直接写：`js("document.title")`	多步骤逻辑拆成多个`await js()`调用
复杂逻辑显式 IIFE，只 return 一次	依赖回调里的`return`被自动包装
模板字符串加`String.raw`	裸写正则单反斜杠
直接消费返回结果	对返回值再`JSON.parse()`