Files
marqdo/doc/design/ext-web-customization/07-assets-script-lifecycle.md
cflmyandCursor 5f91be7c21 docs(web): catalog customization limits and C0–C4 fix designs
Capture route/shell/auth/theme pain points from real sites and lock per-item solution docs before plugin work.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 11:38:20 +08:00

2.2 KiB
Raw Permalink Blame History

解决 7:静态资源与脚本生命周期

问题 研究 §7
优先级 P2 · 波次 C3
触点 web_page_head / web_head · render.rs head 输出 · static 挂载 · web-assets-and-images.md

1. 目标

  1. 默认脚本加载方式不假设作者手写 IIFE 抢在 DOM 前执行成功;提供 defer / module 一等约定。
  2. 静态资源变更可发现:文档化 ?v=,并提供可选自动指纹或 listen 时 mtime 查询参数。

2. 作者 API(草案)

Head 资源表扩展列(向后兼容):

列 说明
rel / 关系 已有;script / module
defer / 推迟 真 → <script defer>(建议默认对 script 为真)
async / 异步 可选
version / 版本 非空则自动追加 ?v=
`头` =
| 关系 | 地址 | 推迟 | 版本 |
|------|------|------|------|
| script | /static/theme.js | 真 | 2026-09-04 |
| module | /static/desk.js | 真 | 3 |

全局:app.asset_version="2026-09-04" 为所有 static 链接统一 bump(可选)。


3. 插件改动点

改动 说明
head 渲染 尊重 defer/async;module → type="module"(已有则核对)
默认 新建 scaffold 的 script 行带 defer
(可选)asset_version listen 时重写 head / 页面内 static URL
文档 「禁止在同步 head 脚本里直接 getElementById 主节点;用 defer 或 DOMContentLoaded」

4. 兼容策略

  • 旧表无 defer 列:保持现网同步行为(或仅对 scaffold/新文档默认 defer,避免静默改变旧站时序)。
  • 更安全:缺省仍同步;Skill 与 scaffold 默认写 defer=真。

5. 验收

场景 期望
defer 脚本读 DOM 登录跳转逻辑在 DOM 就绪后执行
version 列 HTML 中出现 theme.js?v=…
旧示例无新列 仍通过

6. 过渡期 workaround

脚本改 type=module 或放 body 末;手动 ?v= bump;登录逻辑用 DOMContentLoaded。