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>
2.2 KiB
2.2 KiB
解决 7:静态资源与脚本生命周期
| 问题 | 研究 §7 |
| 优先级 | P2 · 波次 C3 |
| 触点 | web_page_head / web_head · render.rs head 输出 · static 挂载 · web-assets-and-images.md |
1. 目标
- 默认脚本加载方式不假设作者手写 IIFE 抢在 DOM 前执行成功;提供
defer/module一等约定。 - 静态资源变更可发现:文档化
?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。