Widget 规则:大小、性能限制和检查代码

大小、文件类型、性能限制以及检查可能失败的所有代码。

阅读约 8 分钟 更新于 2026年11月4日

widget 与其他所有内容一起在 overlay 中运行,而且常常是在性能较弱的电脑上。因此有固定的限制。Livedeck 在三个地方使用相同的数值:本文档、审核前的自动测试,以及 LIVE 期间的 overlay。

包

ZIP 文件

5 MB

解压后总大小

5 MB

单个文件

2 MB

文件

200

路径长度

180 个字符

文件夹层级

8

manifest.json

64 KB

允许的文件类型:html、js、mjs、css、json、svg、txt、md、png、jpg、jpeg、webp、gif、mp3、ogg、wav、woff2。文本文件必须为 UTF-8 编码。图片、声音和字体的实际格式必须与扩展名一致。

不允许的内容

  • HTML、CSS、JavaScript、SVG 或 JSON 中的其他网站地址(http://、https://、ws://、wss:// 或 //host)。注释中的地址不会导致检查失败,但管理员能看到。
  • HTML 中的 iframe、frame、object、embed、portal、base 和 meta refresh
  • WebRTC(RTCPeerConnection、STUN 或 TURN 服务器)、通过 JavaScript 创建的框架(createElement("iframe") 或字符串中的 "<iframe"),以及 dns-prefetch、preconnect 等连接提示。Livedeck 也会在 widget 内禁用这些功能。
  • SVG 文件中的脚本、事件处理程序或 foreignObject
  • 加密的 ZIP 文件、符号链接以及压缩包内嵌套的压缩包

管理员还会看到有关 eval、new Function、WebAssembly、WebSocket、访问存储或 overlay 窗口、挖矿特征以及混淆或压缩代码的提示。提示不会直接导致检查失败,但需要有充分理由。压缩代码请连同可读源码一起放在 src/ 文件夹中提交。

manifest.json、src/ 文件夹以及 .md 或 .txt 文件仅用于审核。Livedeck 绝不会将它们提供给 overlay,因此你的代码无法加载它们。每位用户都会通过各自独立的地址获取你的 widget。

性能限制

页面加载后就绪

3000 ms

LIVE 期间加载页面

15,000 ms

无事件时的 CPU(平均)

2 %

事件极多时的 CPU(平均)

15 %

内存(JavaScript)

64 MB

页面元素数量

3000

单次最长阻塞

200 ms

LIVE 期间

  • overlay 每 2000 ms 检查一次。连续 3 次响应慢于 1000 ms,或 6000 ms 内无任何响应,widget 将被关闭。
  • 如果是 overlay 本身卡住(例如标签页处于后台),绝不会计入你的 widget。
  • 被关闭的 widget 会一直保持关闭,直到下次重新加载。之后编辑器会显示“Widget 已停止”。
提示:保持页面轻量:移除旧元素(入门套件最多显示 maxCards 张卡片),用 CSS 动画代替 JavaScript 循环,没有事件时不要运行计时器。

检查代码

检查未通过时,编辑器或卖家工作室会列出原因。这里列出了所有代码。

ZIP 文件

zip_too_large

ZIP 文件超过 5 MB。

zip_total_too_large

解压后超过 5 MB。

zip_file_too_large

有文件超过 2 MB。

zip_too_many_files

文件超过 200 个。

zip_not_zip

不是 ZIP 文件,或是空文件。

zip_multi_disk

被拆分成多个分卷。请把所有内容打包成一个文件。

zip64_unsupported

不支持 ZIP64。

zip_trailing_data

ZIP 文件末尾之后还有多余数据。

zip_corrupt

ZIP 文件已损坏。

zip_encrypted

ZIP 文件设有密码保护。

zip_unsupported_method

不支持该压缩方式。仅允许 Stored(不压缩)和 Deflate(默认)。

zip_header_mismatch

压缩包内部信息互相矛盾。

zip_overlap

压缩包内的文件互相重叠。

zip_crc_mismatch

校验和错误,有文件已损坏。

zip_symlink

包内含有符号链接。

zip_bad_name

文件名无效:非 ASCII 字符但未使用 UTF-8、包含 ../、绝对路径、特殊字符、超过 180 个字符或文件夹层级超过 8 层。

zip_duplicate_name

某个文件在压缩包中出现了两次。

zip_nested_archive

压缩包内还有压缩包(例如 ZIP 里套 ZIP)。

文件和内容

manifest_missing

缺少 manifest.json。它必须位于 ZIP 的根目录,或其唯一的文件夹内。

manifest_invalid

manifest.json 无效。错误列在下方(代码见“manifest.json 参考”)。

entry_missing

entry 中指定的启动文件不在包内。

file_type_not_allowed

不允许此文件类型。

file_content_mismatch

内容与扩展名不符(例如 JPG 文件命名为 .png)。

file_not_utf8

文本文件未以 UTF-8 保存。

file_empty

文件为空。

external_reference

文件中包含其他网站的地址(附行号)。

forbidden_markup

包含不允许的 HTML(iframe、frame、object、embed、portal、base、meta refresh),或 SVG 文件中含有脚本。

forbidden_api

包含绕过网络限制的代码:WebRTC(RTCPeerConnection、STUN/TURN)、通过 JavaScript 创建框架(createElement("iframe")、字符串中的 "<iframe")或连接提示(dns-prefetch、preconnect、prerender、prefetch)。

自动测试

test_failed 表示自动测试至少超出了一项限制。具体原因列在下方,每项都附有测量值和限制值。

perf_no_ready

Widget 加载后从未向 overlay 报告。通常是缺少 <script src="/sdk/v1.js">,或页面一直没有加载完成。

perf_ready_slow

就绪太晚:页面加载后超过 3000 ms。

perf_unresponsive

未响应 overlay 的检查,或响应太慢(代码阻塞了浏览器)。

perf_navigated

Widget 跳转到了其他页面或重新加载了页面。

perf_flood

Widget 向 overlay 发送的消息过多。

perf_idle_cpu

空闲时 CPU 占用超过 2 %。

perf_storm_cpu

事件密集时 CPU 占用超过 15 %。

perf_heap

内存占用超过 64 MB。

perf_dom

页面元素超过 3000 个。

perf_long_task

单次阻塞浏览器超过 200 ms。

network_attempt

尝试从其他网站加载内容(会显示主机名)。

runtime_errors

仅为提示,不会导致失败:测试期间出现 JavaScript 错误。管理员可以看到第一个错误。

这篇文章对你有帮助吗?