限制与常见问题

编译相关

• 所有应用都由浏览器内编译器打包，Node 内置模块按以下分级支持（node: 前缀写法同样适用）：
  • 浏览器 polyfill，可正常使用：process / events / util / stream / url / querystring / assert / string_decoder 等
  • 本地实现：path、buffer、timers 完整可用；crypto 只支持部分 API（Web Crypto、randomBytes、pbkdf2，以及 md5 / sha1 / sha224 / sha256 的 createHash，不支持 scrypt）；zlib 只支持异步的 gzip / deflate（*Sync、Brotli 和流式接口调用时报错）；fs / fs/promises 只支持异步 API，且只能在终端 run 临时脚本里使用，应用源码中调用会以 WORKSPACE_LEASE_REQUIRED 拒绝
  • 可以 import 但调用即报错（错误信息带 [lf-node-shim] 前缀）：http / https / net / tls / dns / os / readline / tty 等
  • 直接编译失败：child_process / cluster / worker_threads / vm / v8 / inspector / module / repl
• 本地模块请用标准 ESM import。@require 只接受内置库 id，写本地文件（如 // @require ./lib.js）会编译失败
• 插件构建只读入口文件的 @require：组件或工具文件里用到的内置库也必须在入口声明，非入口文件头部的 @require 只在终端直接 run 该文件时生效（编辑器给 Warning）
• Vue 通过正常 import { createApp } from "vue" 引入，不再作为内置运行时别名

运行时相关

• LFHttp 只拒绝本机 PluginX 客户端端口（任何回环写法的 41720）、chrome-extension://、file:// 与非 http(s) 目标，重定向后的最终地址同样复核；只校验字面主机名。本地客户端只能经 LFHttp.client 访问。默认携带目标域名已有 cookie，也可以用 headers.Cookie 显式指定（会整体替换浏览器自动附带的 cookie）；Referer / User-Agent 等浏览器保留头在网络层写入，结果见响应的 headerOverrides
• LFNetwork 在已保存 bundle、liveDebug 主路径（USER_SCRIPT 世界）与 run --tab MAIN world 脚本（经网络中继桥）均可用；代码中直接使用须显式 // @require network（@require dom 不够）
• LFRuntime.readFile / writeFile / execTerminalCommand 只能在终端 run 临时脚本（run / run -c / run --tab / run --target background）里直接调用。应用源码（liveDebug、已启用 / 已安装、后台应用）直接调用会编译报错，须用 LFRuntime.cli.register({ workspace: ['read' | 'write' | 'exec'] }) 注册命令，在 handler 里通过 ctx.workspace.readFile / writeFile / exec 访问，租约只在本次 plugincmd call 期间有效
• 本机命令执行、本机文件访问与 CLI 注册表请求只接受 PluginX 编辑器页面发起，插件应用（页面注入、后台、USER_SCRIPT world）直接发送这些扩展消息会以 EACCES_PERMISSION 被拒绝
• LFStore 按 JSON 存储：值里含 Map / Set / 函数 / Symbol / BigInt / 循环引用时 set 直接报错并指出路径（如 at value.cache），请先转成普通 JSON 数据
• 使用 LFRuntime.network.onResponse / interceptRequest / interceptResponse 拦截页面请求必须在入口头部声明 @intercept，否则点「编译」直接报错（liveDebug 与 run --tab 不检查此项）

IDE 相关

• 保存（Ctrl+S）只存源码；点「编译」（会自动先保存）才会编译并更新已注册的产物。只保存不编译时，已启用的应用和刷新后的页面仍运行上一次编译的版本
• 文件树顶部可新建文件/文件夹，右键菜单支持重命名、删除，终端也可用 mv / rm 调整；重命名或移动入口文件时，入口设置会自动跟随
• 首次编译 npm 依赖需要联网下载，之后命中 IndexedDB 缓存（可在「系统信息」查看缓存量）
• liveDebug 按浏览器 documentId 判断页面生命周期：SPA 弹窗、history.pushState 等仅改变 URL 但不更换 document 的操作不会重注入，也不会注销 CLI 命令。只有完整导航/刷新产生新 document 时，旧 USER_SCRIPT 和正在执行的 plugincmd 调用才会结束；新 document 加载完成后会自动重注入并恢复注册，已中断的调用需在 injectionHealthy: true 后重试
• 若具名 USER_SCRIPT world 的 messaging 配置失败，liveDebug 会自动重试三次，再报错并停止注入，不会运行缺少 LFStore/LFUser/LFNetwork/CLI 能力的半残实例；环境恢复后执行 liveDebug reload 重试

权限相关

已安装应用要真正运行，浏览器必须为扩展开放 userScripts 能力（「允许运行用户脚本」开关或开发者模式）。未开启时应用管理页会出现引导横幅，按步骤开启后点「重新检测权限」即可。