必须删除Bootstrap栅格类，否则Masonry会因flex/float与JS“砌砖”逻辑冲突而重叠错位；需用语义化容器、纯子项标签、CSS控宽、imagesLoaded前置校验图片加载，并监听resize重排布局。
Bootstrap 栅格类必须全删，否则 Masonry 会重叠错位
直接在 .row 里套 .col-md-4，再初始化 Masonry，99% 会出问题。因为 Bootstrap 的栅格靠 flex 或 float 做行内布局，而 Masonry 是 JS 拿所有子项重新按列“砌砖”——两者逻辑冲突，CSS 宽度、 margin、flex-basis 全都会干扰 Masonry 的位置计算。
实操建议：
- 容器只保留语义化结构，比如
<div class="masonry">，不要加row - 子项用纯标签（如
<article>或<div class="item">），移除所有col-*类 - 宽度改由 CSS 控制，例如：
width: calc(33.333% - 1rem);（对应三列 + 间隙） - 若需响应式列数变化，不能只改 CSS，必须调用
masonry.layout()
imagesLoaded 不是可选插件，是 Masonry 正常工作的前提
没等图片加载完就执行 masonry()，JS 读到的子项高度全是 0 或默认值，结果就是卡片堆叠、错位、漏排——这不是 bug，是必然行为。
常见错误现象：Uncaught TypeError: Cannot read property 'offsetTop' of undefined 或视觉上大量重叠。
实操建议：
- 引入顺序必须是：
jQuery→imagesLoaded→Masonry - 初始化必须包裹在
imagesLoaded回调里：$('.masonry').imagesLoaded(() => { $('.masonry').masonry({ itemSelector: '.item' }); }); - 如果子项含
<picture>或懒加载data-src，得手动触发imagesLoaded或用background-image的伪元素 hack
移动端 Safari 的 column-count 兼容性坑比想象中深
虽然 column-count 看似轻量，但 iOS Safari（尤其旧版）对 break-inside: avoid 支持不稳定，经常导致卡片被截断、图片溢出、列间间距错乱。2026 年最新测试显示：Safari 17+ 表现尚可，但 iOS 15 及更早版本仍存在渲染抖动。
实操建议：
- 若必须用 CSS 方案，给子项加
break-inside: avoid-column;（比avoid更稳妥） - 图片强制加
max-width: 100%; height: auto;，避免撑破列宽 - 用
@supports (column-count: 3)包裹样式，并 fallback 到单列或 flex wrap - 真要保兼容又不想写 JS？直接放弃
column-count，Masonry + imagesLoaded 是当前最稳路径
响应式列数切换时，Masonry 不会自动重排
很多人以为改了 @media 里的 width 或加个 col-6 类就能响应式，但 Masonry 初始化后不会监听窗口 resize 或类名变更——它只认初始 DOM 和尺寸快照。
实操建议：
- 监听
resize事件，节流后调用masonry.layout() - 如果用 Bootstrap 断点切换列数（比如从 3 列变 1 列），应在 JS 中同步更新
columnWidth配置并重排 - 避免在
itemSelector里用动态类名（如.col-sm-6），会导致 Masonry 找不到目标项
真正难的不是引入 Masonry，而是让它的计算和页面生命周期对齐——图片加载时机、DOM 就绪状态、CSS 宽度生效顺序，三者稍有错位，瀑布流就塌一半。
