flask 项目中引入外部 javascript 动画（如光标粒子特效）时，页面无响应或效果不完整，通常并非后端或脚本本身的问题，而是因 html 文档流未占据足够视口空间导致 dom 元素尺寸为零，使 canvas 或绝对定位动画无法渲染。
flask 项目中引入外部 javascript 动画（如光标粒子特效）时，页面无响应或效果不完整，通常并非后端或脚本本身的问题，而是因 html 文档流未占据足够视口空间导致 dom 元素尺寸为零，使 canvas 或绝对定位动画无法渲染。
在使用 Flask 渲染前端动画（例如 CodePen 上的 Sparkle Trail 和 Dust Cursor 效果）时，开发者常遇到“脚本已加载但无视觉反馈”或“仅显示拖尾、缺失闪烁粒子”的现象。此时容易误判为 Flask 静态文件路径错误、url_for 用法不当，或 JavaScript 兼容性问题——但实际根源往往在CSS 布局层面。
根本原因：body 默认高度为 0
HTML 页面默认
不继承视口高度。当动画脚本（如该特效）依赖 document.body 或 document.documentElement 计算坐标、创建全屏 Canvas、或对 body 进行绝对定位操作时，若 body 高度为 auto（即内容高度为 0），则：- Canvas 元素被创建但尺寸为 0×0；
- 粒子系统因 getBoundingClientRect() 返回 {height: 0} 而跳过渲染逻辑；
- 光标事件监听正常，但绘制目标区域不可见。
这正是 CodePen 能直接运行而本地 Flask 页面失效的关键差异：CodePen 的预览容器默认注入了 html, body { height: 100%; } 等隐式样式，而 Flask 渲染的裸 HTML 没有。
解决方案：显式声明视口高度
在 index.html 中为
立即学习“前端免费学习笔记（深入）”；
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Sparkle Trail and Dust Cursor</title>
<style>
/* 关键修复：确保 body 占满视口 */
html, body {
margin: 0;
padding: 0;
height: 100vh; /* 必须使用 vh，而非 % */
overflow: hidden; /* 可选：防止滚动干扰动画 */
}
</style>
</head>
<body>
<h1>Sparkle Trail and Dust Cursor</h1>
<script src="{{ url_for('static', filename='js/script.js') }}"></script>
</body>
</html>✅ 注意：
- 使用 height: 100vh（视口高度单位）而非 height: 100%，因为 % 需要父元素有明确高度，而 html 在某些浏览器中可能未自动继承 100vh；
- 若需支持移动端缩放，可补充 @supports (height: 100dvh) 使用 100dvh（动态视口高度），但当前场景 100vh 已足够；
- 确保 script.js 已正确放入 static/js/ 目录（Flask 默认静态文件夹），且路径拼写与 url_for 一致（大小写敏感）。
验证与调试建议
- 打开浏览器开发者工具（F12），检查 元素的 computed height 是否为非零值（如 100vh → 实际像素值）；
- 在 Console 中执行 document.body.getBoundingClientRect()，确认 height > 0；
- 临时添加 到 内，直观验证布局是否覆盖全屏。
完成上述调整后，原 CodePen 中的光标粒子轨迹、+ 形闪光等效果将完整呈现。这一案例再次印证：在全栈开发中，前后端职责边界清晰，但前端渲染效果的成败，常系于一行 CSS 的取舍。
