bubbly-bg需按项目类型选安装方式：html用cdn脚本，npm工程用esm导入；必须在body内加载并调用bubbly()启动；自定义需同步设置background和bubbles.fill；调整动画需控制speed、count等参数；防遮挡须指定parent容器并设宽高。
想给网页加个轻量又灵动的气泡背景，却卡在第一步引入失败或空白无效果？bubbly-bg仅750字节（gzip后），纯原生JS、零依赖，但配置稍有偏差就会不渲染、不动画、甚至覆盖页面内容。
确认项目类型，选对安装方式
先判断你用的是静态HTML页面、现代前端工程（如Vite/React/Vue），还是本地开发环境。不同场景必须匹配对应安装路径，混用会导致bubbly is not defined错误或canvas不挂载。
方法一：纯HTML页面（推荐新手首选）→ 直接在底部添加CDN脚本：
<script src="https://cdn.jsdelivr.net/npm/bubbly-bg@1.0.0/dist/bubbly-bg.js"></script>
方法二：npm工程 → 终端执行：npm install bubbly-bg，然后在入口JS文件（如main.js）顶部写import 'bubbly-bg';。注意：不要用require()，ESM导入才触发自动注册。
【关键前提】脚本必须在内加载，且不能放在中未加defer——否则DOM未就绪，canvas无法插入。
让气泡动起来：三行代码启动
安装完后，立即测试基础效果。别急着改颜色，先确保能跑通：
在最底部（CDN脚本下方）加：
<script>bubbly();</script>
刷新页面。若看到全屏淡蓝气泡缓慢浮升，说明成功；若页面白屏或报错，检查浏览器控制台是否提示Failed to load resource——大概率是CDN链接拼写错误或网络拦截。
这一步不能跳过。很多用户直接进配置环节，结果连canvas都没生成，后续所有自定义都无效。
自定义气泡颜色与背景渐变
默认蓝泡泡太单调？用对象参数覆盖即可。重点在于background和bubbles.fill必须同时设置，否则气泡会消失或背景变黑。
步骤一：复制以下代码，替换掉原来的bubbly();
bubbly({<br> background: (ctx) => {<br> const gradient = ctx.createLinearGradient(0, 0, ctx.canvas.width, ctx.canvas.height);<br> gradient.addColorStop(0, "#0f2027");<br> gradient.addColorStop(1, "#203a43");<br> return gradient;<br> },<br> bubbles: {<br> fill: () => `hsla(${Math.random() * 60 + 30}, 100%, 70%, ${Math.random() * 0.3})`<br> }<br>});
步骤二：保存并刷新。深青色线性渐变背景+橙黄系半透明气泡即刻呈现。
⚠️ 注意：fill函数里必须返回带alpha通道的CSS颜色（如hsla或rgba），写成#ff9900会因不透明导致气泡堆叠发糊。
调整动画节奏与气泡密度
默认气泡上升慢、数量少？通过bubbles子属性精细调控：
方法一：加快上升速度+增大尺寸
bubbles: {<br> speed: 0.2,<br> size: 8<br>}
方法二：增加气泡总数（默认约30个）
bubbles: {<br> count: 60<br>}
方法三：混合使用（推荐）
bubbles: {<br> count: 45,<br> speed: 0.15,<br> size: 6,<br> fill: () => `hsla(${Math.random() * 30 + 200}, 80%, 65%, ${Math.random() * 0.25})`<br>}
【易错点】speed值超过0.3会导致气泡飞出画布顶部不可见；count超过80可能在低端设备引发卡顿。
防止气泡遮挡页面内容
气泡canvas默认插入开头，会压在你的导航栏、按钮上方。必须手动指定插入位置：
第一步：在HTML中你想显示气泡的容器上加id="bubbly-canvas"，例如：<div id="bubbly-canvas" style="position:relative;width:100%;height:100vh;"></div>
第二步：调用时传入该元素：
const container = document.getElementById('bubbly-canvas');<br>bubbly({<br> parent: container,<br> ...其他配置<br>});
第三步：确保容器有明确宽高（如height: 100vh）且position: relative——否则canvas会塌陷为0×0像素，什么也看不到。
