3D走马灯双端实现：网页端CSS 3D与小程序Canvas 2D方案全解析

做活动落地页的时候，产品提了个需求：要一版能转圈的卡片展示效果，卡片上有图片有文字，能前后翻动、有立体感，做成“3D走马灯”。平台限定是网页端和小程序端都要上，两端视觉必须一致。这个需求看着简单，实际动手后才发现，网页端和小程序端的实现路径差别比想象中大得多：一端走 CSS 3D transform 或是 WebGL，另一端只能老老实实用 Canvas 2D 手写投影；一端处理 mouse 事件，另一端处理 touch 事件；更不用说图片域名、安全区、Canvas 高清适配这些小程序特有的坑。这篇文章就把这次实现从选型、几何计算到两端代码完整拆出来，给准备做同样功能的人当一份能直接抄作业的参考。

1. 为什么选 3D 走马灯：从产品需求到技术选型的收敛

1.1 这类需求一般出现在什么场景

3D 走马灯不是我凭空想做的，它是在好几个活动里反复出现的通用组件。最常见的是官网首页的核心卖点轮播，产品经理希望首屏不是普通的左右滑动 Banner，而是一个立体的“卡片环绕”效果，能把 6-8 个卖点同时展示在用户视野里；其次是微信小程序里的活动页、排行榜、奖品墙，一张卡片代表一个奖品或一个作品，用户左右滑动时能感受到卡片在空间中旋转的冲击力；还有一些作品集、招聘页面、年会照片墙，都会用这种效果来增加视觉差异化。

其实 2D 轮播已经能满足“切换”这个基本需求，为什么还要上 3D？核心是信息密度和氛围感。2D 轮播同一时刻只能完整看到一张卡片，其他卡片藏在屏幕外；3D 走马灯在同一个画面中能同时展示多张卡片的正面和侧面，两侧卡片带着透视感“转”下去，给用户一种“卡片在空间中环绕”的心理暗示。这种效果特别适合运营活动页，因为点击率在视觉新鲜感的驱动下往往比普通轮播高不少。

1.2 两端可选的实现方案对比

在写代码之前，我先列了一个方案对比表，把所有能想到的路子都过了一遍，避免写了一半发现技术栈撑不住。

我最终选的是“网页端用 CSS 3D transform，小程序端用 Canvas 2D 手写投影”这个组合。原因很直接：网页端 CSS 3D 是零依赖、最稳、效果最好的方案，写起来十几行就搞定；小程序端塞一个 Three.js 会让主包体积明显变大，而且 WXSS 的 3D 支持在真机上存在很明显的环境差异，不如用 Canvas 2D 自己掌控一切。两个端虽然渲染方式不同，但底层共享同一套“卡片总数量、旋转角度、半径、偏移量”的配置结构，这样既省了小程序包体积压力，又保证了视觉一致性。

1.3 技术选型的最终结论

项目的整体架构可以概括成三层：数据层、数学层、渲染层。数据层存放卡片列表、图片 URL、标题、跳转链接；数学层负责把“旋转角度”转换成“每张卡片的空间坐标”；渲染层在不同端做不同实现。网页端的渲染层是 CSS 3D transform，小程序端的渲染层是 Canvas 2D 绘制。这样抽离之后，后续新增一个 App 端，只需要再写一个渲染层，数学层和数据层完全复用。

2. 3D 走马灯的空间几何：核心不是 rotation，而是圆柱体半径与相机距离

2.1 卡片布局：把所有卡片铺在一个虚拟圆柱面上

要做出“环绕”的 3D 效果，不能把 6 张卡片平铺在一行然后旋转，那样转起来只是个平面滚动条，没有任何立体感。正确的做法，是把每张卡片当成圆柱体侧面的一部分，卡片中心点分布在同一个圆周上，旋转的时候所有卡片整体绕圆柱中心轴（也就是 Y 轴）转。

假设有 N 张卡片，那么相邻卡片之间的中心夹角是：
angle = 360 / N

每张卡片的初始化变换是：
transform: rotateY(angle * i) translateZ(radius)

这里面的逻辑是：先把卡片绕 Y 轴旋转到它对应的方向，然后再沿 Z 轴正方向平移 radius，这样卡片就落在了以原点为圆心、半径为 radius 的圆周上。所有卡片执行完这个变换后，再从 X 轴正方向看过去，就是一组环绕圆柱面的卡片阵列。旋转动画只需要改变最外层舞台的 rotateY，卡片自身的绝对位置不用反复修改。

2.2 半径公式：为什么不能随手填一个数字

真正容易出错的是 radius 的取值。如果半径太大，卡片之间有巨大的空隙，转起来像一群散开的照片；如果半径太小，相邻卡片会互相穿插、遮挡严重，数字看起来非常拥挤。

一个合理的起始半径公式是：
radius = (cardWidth / 2) / tan(angle / 2)

推导逻辑是这样的：相邻卡片在圆周上的“直线距离”如果刚好等于卡片宽度，那卡片就不会互相重叠。这个直线距离是一条弦，圆心角是 angle，根据弦长公式，chord = 2 * radius * sin(angle / 2)；令 chord = cardWidth，得到 radius = cardWidth / (2 * sin(angle / 2))。但实际视觉上，CSS 的 translateZ 之后看到的间距会比弦长略大，所以我一般会在算出的 radius 基础上再乘一个 1.2~1.4 的安全系数，给前后卡片之间留出呼吸感，避免画面显得太拥挤。

举个例子：6 张卡片，卡片宽度 220px，可视区域 375px。angle = 360 / 6 = 60°，radius = (220 / 2) / tan(30°) = 110 / 0.577 ≈ 190.5px，乘以安全系数 1.3 后约 248px。整个圆柱直径约 496px，超过可视区宽度，这样两侧卡片会自然“转”向深处，产生明显的透视效果。如果卡片数量改成 10 张，angle = 36°，radius = 110 / tan(18°) ≈ 338px，再乘 1.3 约 440px。可以看到卡片数量和半径是强耦合的，改数量的时候必须重算，不能只在代码里加一个数组项。

2.3 透视投影与深度排序

在 CSS 3D 中，给最外层容器设置 perspective 后，浏览器会自动执行透视投影：z 值越大（离观察者越远）的物体看起来越小。perspective 值越小透视越强烈，越大越接近正交投影。我常用的初始值是 900px 到 1500px，视距太小会让卡片变形严重，太大则会让纵深效果变得很弱。

在 Canvas 2D 里，这一步必须自己实现。核心公式是：
screenScale = f / (f + z)

其中 f 是视距（相当于 CSS 的 perspective），z 是卡片中心点在当前帧的世界坐标深度。每张卡片在某一帧的位置是：
x = radius * sin(rotation + angle * i)
z = radius * cos(rotation + angle * i)

绘制顺序按 z 升序排列，也就是先画远处的卡片，再画近处的卡片，让近处覆盖远处，这是经典的“画家算法”。CSS 3D 方案里浏览器会自动处理遮挡和层级，但 Canvas 2D 里如果不排序，就会出现前面的卡片被后面的卡片盖住的诡异现象。

这里有一个容易忽略的边界条件：f + z 必须大于 0。如果 z 为负数且绝对值接近 f，scale 会趋向无穷大；如果 z < -f，scale 变为负数，卡片会翻转。所以视距 f 的设置要大于半径 radius，保证卡片转到背面时不会穿帮。

3. 网页端实现：CSS 3D transform 的完整搭建过程

3.1 基础 DOM 结构与样式

网页端我用的是纯 CSS 3D transform，零依赖，只要浏览器不支持太老的版本都能跑。先看 HTML 结构：

html复制<div class="carousel">
  <div class="stage" id="stage">
    <div class="card">
      <img src="..." alt="卡片1">
      <p>标题</p>
    </div>
    <div class="card">
      <img src="..." alt="卡片2">
      <p>标题</p>
    </div>
    <!-- 更多卡片 -->
  </div>
</div>

关键样式是这样：

css复制.carousel {
  perspective: 1200px;
}

.stage {
  position: relative;
  width: 260px;
  height: 340px;
  transform-style: preserve-3d;
}

.card {
  position: absolute;
  left: 50%;
  top: 50%;
  width: 220px;
  height: 320px;
  margin-left: -110px;
  margin-top: -160px;
  border-radius: 12px;
  overflow: hidden;
  backface-visibility: hidden;
  will-change: transform;
}

注意，stage 的尺寸就是圆柱圆心的基准，卡片用 margin 负值居中，而不是用 left/top 直接逐个设置位置。这样做的好处是，后续如果卡片宽度变化，只需要改一个变量，不用挨个调整。

perspective 放在 .carousel 上而不是 .stage 上，这是一个重要细节。如果把 perspective 直接写在 .stage 上，观察视点会被每个子元素单独解释，容易出现卡片整体扭曲的问题；正确做法是由最外层容器建立统一视窗。

3.2 JS 初始化与渲染循环

初始化逻辑很简单，根据第 2 节的公式把每张卡片放到对应的位置：

javascript复制const N = 6;
const cardWidth = 220;
const angleStep = (2 * Math.PI) / N;
const radius = (cardWidth / 2) / Math.tan(angleStep / 2) * 1.3;
let rotation = 0;

const cards = document.querySelectorAll('.card');
cards.forEach((card, i) => {
  card.style.transform = `rotateY(${angleStep * i}rad) translateZ(${radius}px)`;
});

function render() {
  const stage = document.getElementById('stage');
  stage.style.transform = `rotateY(${rotation}rad)`;
}

这里用弧度而不是角度，CSS 的 rotateY 直接接受 rad 单位，少一层换算。动画循环使用 requestAnimationFrame，而不是 setInterval，因为浏览器会在下一帧重绘前自动执行，避免掉帧和卡顿。

3.3 拖拽与惯性动画

鼠标拖拽是 3D 走马灯的标配交互。我的实现思路很朴素：按下时记录起始位置，移动时计算位移增量叠加到 rotation 上，松手时保留最后的移动速度，然后在动画循环里让速度按比例衰减，形成自然的惯性滑动。

javascript复制let dragging = false;
let lastX = 0;
let velocity = 0;

const stage = document.getElementById('stage');

stage.addEventListener('mousedown', (e) => {
  dragging = true;
  lastX = e.clientX;
  velocity = 0;
});

window.addEventListener('mousemove', (e) => {
  if (!dragging) return;
  const delta = e.clientX - lastX;
  lastX = e.clientX;
  rotation += delta * 0.005;
  velocity = delta * 0.005;
});

window.addEventListener('mouseup', () => {
  dragging = false;
});

function animate() {
  if (!dragging) {
    rotation += velocity;
    velocity *= 0.95;
    if (Math.abs(velocity) < 0.0005) velocity = 0;
  }
  render();
  requestAnimationFrame(animate);
}

animate();

灵敏度系数 0.005 是根据视觉手感调出来的，鼠标横向移动 200px 时，旋转角度变化约 1 弧度，正好够 6 张卡片转 60° 左右。如果卡片数量多，可以适当调大，让每次拖拽覆盖的卡片跨度更大。

这里的核心设计是：动画循环只更新舞台的 rotateY，不更新每个卡片自身的 transform。因为卡片自身的旋转和位移在初始化后就不变了，如果每帧把所有卡片都重新计算一遍 transform，会触发大量样式重算，性能下降很明显。把变化最小化，是 3D 动画优化里很基础但很重要的一招。

3.4 响应式适配与自动播放

卡片尺寸在不同屏幕上需要缩放，否则大屏上显得小气，小屏上又溢出。我的做法是用视口宽度计算一个缩放系数，然后作用到整个 carousel 容器上：

javascript复制const carousel = document.querySelector('.carousel');
function handleResize() {
  const scale = Math.min(1, window.innerWidth / 750);
  carousel.style.transform = `scale(${scale})`;
}
window.addEventListener('resize', handleResize);
handleResize();

自动播放也很简单，在 animate 里加一段无人交互时的递进逻辑：

javascript复制let lastInteraction = Date.now();

function animate() {
  // 鼠标操作时暂停自动播放
  if (!dragging) {
    if (Date.now() - lastInteraction > 5000) {
      rotation += 0.008;
      velocity = 0.008;
    }
    rotation += velocity;
    velocity *= 0.95;
    if (Math.abs(velocity) < 0.0005) velocity = 0;
  }
  render();
  requestAnimationFrame(animate);
}

用户停止操作 5 秒后开始自动匀速旋转，速度很低，不至于打扰阅读。注意自动播放的增量也要给到 velocity，否则突然接回用户拖拽时会出现速度突变。

4. 小程序端实现：Canvas 2D 手写 3D 投影

4.1 为什么小程序不直接复用 CSS 3D

很多从小程序开发经验的朋友会问：微信小程序的 WXSS 不也支持 transform 吗，为什么不用 CSS 3D 方案直接平移过去？我实测下来有几个原因：

第一，WXSS 对 transform-style: preserve-3d 的支持在真机上不稳定，部分 Android 低版本基础库会直接把 3D 效果退化成 2D，排查起来非常费劲；第二，小程序页面层级里经常要叠加自定义导航栏、弹窗、loading 组件，CSS 3D 元素和其他组件之间的层级管理很容易出问题；第三，小程序里没有 DOM 操作，不能像网页那样通过 querySelector 直接修改某个元素的 style，所有样式都要走 setData，高频更新 transform 会带来严重的性能损耗。

所以我选择用 Canvas 2D 画卡片。Canvas 2D 在小程序里的兼容性非常好，iOS 和 Android 都能稳定运行，绘制逻辑完全可控，唯一的代价是 3D 数学得自己写。但第 2 节已经把公式推完了，这里只是翻译成 Canvas 绘制逻辑而已。

4.2 Canvas 节点获取与高清屏适配

小程序的 Canvas 2D 有新旧两套接口。新的 type="2d" 接口从基础库 2.9.0 开始支持，返回的是标准 canvas 节点，绘制 API 更接近浏览器环境，推荐使用。老的 wx.createCanvasContext 也有不少人用，但它在真机上有一些兼容性坑，新项目建议直接上新的。

WXML 结构：

html复制<canvas
  type="2d"
  id="carouselCanvas"
  class="carousel-canvas"
  bindtouchstart="onTouchStart"
  bindtouchmove="onTouchMove"
  bindtouchend="onTouchEnd"
></canvas>

获取节点并初始化：

javascript复制Page({
  onReady() {
    const query = wx.createSelectorQuery();
    query.select('#carouselCanvas')
      .fields({ node: true, size: true })
      .exec((res) => {
        if (!res || !res[0]) return;
        const canvas = res[0].node;
        const ctx = canvas.getContext('2d');
        const width = res[0].width;
        const height = res[0].height;
        const dpr = wx.getWindowInfo().pixelRatio;

        canvas.width = width * dpr;
        canvas.height = height * dpr;
        ctx.scale(dpr, dpr);

        this.canvas = canvas;
        this.ctx = ctx;
        this.canvasWidth = width;
        this.canvasHeight = height;

        this.loadImages();
      });
  }
});

注意高清屏适配：在 iPhone 上 dpr 可能是 3，如果不把 canvas 的实际像素放大，绘制出来的卡片会明显发虚。放大后调用 ctx.scale(dpr, dpr)，后续所有绘制坐标都用逻辑像素，不用再管物理像素。

wx.getWindowInfo() 是较新的 API，替代了旧的 wx.getSystemInfoSync()。我这里特意用新 API，因为旧接口在部分新版本基础库里已经标记为不推荐使用了。

4.3 图片加载与绘制主循环

小程序里不能直接用 new Image() 再设置 src，必须在 canvas 节点上通过 canvas.createImage() 创建图片对象，等 onload 之后再绘制。远程图片域名必须在小程序后台的 downloadFile 合法域名里配置过，否则真机上图片加载不出来，开发工具里勾选了“不校验合法域名”才能看到效果。

javascript复制loadImages() {
  const cards = this.data.cards; // 卡片数据数组
  const loaded = cards.map((card) => {
    return new Promise((resolve) => {
      const img = this.canvas.createImage();
      img.onload = () => {
        resolve({ ...card, img });
      };
      img.onerror = () => {
        resolve({ ...card, img: null });
      };
      img.src = card.imageUrl;
    });
  });

  Promise.all(loaded).then((items) => {
    this.cards = items;
    this.startRenderLoop();
  });
}

绘制主循环把第 2 节的公式直接落地：

javascript复制render() {
  const ctx = this.ctx;
  const { canvasWidth, canvasHeight } = this;
  const centerX = canvasWidth / 2;
  const centerY = canvasHeight / 2;
  const cardW = 220;
  const cardH = 320;
  const f = 1200;
  const angleStep = (2 * Math.PI) / this.cards.length;
  const radius = (cardW / 2) / Math.tan(angleStep / 2) * 1.3;

  ctx.clearRect(0, 0, canvasWidth, canvasHeight);

  const items = this.cards.map((card, i) => {
    const angle = this.rotation + angleStep * i;
    const x = radius * Math.sin(angle);
    const z = radius * Math.cos(angle);
    const scale = f / (f + z);
    return { card, x, z, scale };
  });

  // 深度排序：z 越小越远，先画
  items.sort((a, b) => a.z - b.z);

  items.forEach((item) => {
    const sx = centerX + item.x * item.scale;
    const sy = centerY;
    const drawW = cardW * item.scale;
    const drawH = cardH * item.scale;

    if (!item.card.img) {
      // 画占位背景
      ctx.fillStyle = '#e0e0e0';
      ctx.fillRect(sx - drawW / 2, sy - drawH / 2, drawW, drawH);
      return;
    }

    ctx.drawImage(item.card.img, sx - drawW / 2, sy - drawH / 2, drawW, drawH);
  });
}

这段代码实现了最基本的缩放远近效果，但缺少侧向透视。Canvas 2D 的 drawImage 只支持矩形绘制，不支持任意四边形变换，所以要做更逼真的侧脸效果，我用一个轻微的斜切近似模拟：

javascript复制const skewAngle = Math.atan2(item.x, f + item.z);
ctx.save();
ctx.translate(sx, sy);
ctx.transform(1, 0, Math.tan(skewAngle) * 0.3, 1, 0, 0);
ctx.drawImage(item.card.img, -drawW / 2, -drawH / 2, drawW, drawH);
ctx.restore();

这个斜切系数 0.3 是手动调出来的，太大会让卡片看起来明显失真，太小又没有立体感。如果你的设计稿要求更精细的透视纹理，可以考虑用 setTransform 做仿射变换，或者直接上 WebGL，但对于走马灯这个场景，斜切已经足够。

4.4 touch 事件映射、惯性滑动与点击判定

小程序的 touch 事件和网页的 mouse 事件类似，差别在于要自己维护客户端坐标。核心逻辑：

javascript复制onTouchStart(e) {
  this.touchStartX = e.touches[0].clientX;
  this.lastX = e.touches[0].clientX;
  this.touchStartTime = Date.now();
  this.isDragging = true;
  this.velocity = 0;
},

onTouchMove(e) {
  if (!this.isDragging) return;
  const x = e.touches[0].clientX;
  const delta = x - this.lastX;
  this.lastX = x;
  this.rotation += delta * 0.005;
  this.velocity = delta * 0.005;
},

onTouchEnd() {
  this.isDragging = false;
  this.touchEndTime = Date.now();
  const totalDelta = this.lastX - this.touchStartX;
  const duration = this.touchEndTime - this.touchStartTime;
  if (Math.abs(totalDelta) < 5 && duration < 200) {
    this.handleCardTap();
  }
}

单击与滑动的判定很关键：如果用户是滑动，结束后就不该触发点击事件；如果只是轻点，就应该触发卡片点击跳转。我用的判据是总位移小于 5px 且持续时间小于 200ms，实测下来误触率很低。

惯性滑动在 requestAnimationFrame 循环里做，逻辑和网页端完全一致：

javascript复制startRenderLoop() {
  const loop = () => {
    if (!this.isDragging) {
      this.rotation += this.velocity;
      this.velocity *= 0.95;
      if (Math.abs(this.velocity) < 0.0005) this.velocity = 0;
    }
    this.render();
    this.canvas.requestAnimationFrame(loop);
  };
  this.canvas.requestAnimationFrame(loop);
}

这里用的是 canvas.requestAnimationFrame 而不是 wx.nextTick 或 setTimeout，因为 canvas 节点原生支持 requestAnimationFrame，会比 setTimeout 更贴近真机刷新率。

5. 两端性能与体验优化：从掉帧、图片加载到真机手感

5.1 图片资源优化是关键

3D 走马灯卡顿的元凶，绝大多数是图片资源没优化好，而不是算法本身的问题。如果给 Canvas 2D 直接加载一张 2000px 宽的原图，每帧都要做一次大尺寸 drawImage，CPU 和 GPU 的负载会非常明显。

我的经验是：服务端在返回图片时，直接加上缩放参数，把图片宽度限制在 750px 左右。375px 的逻辑宽度，在 3 倍屏上对应 1125px 物理像素，但实际绘制时卡片在屏幕上的逻辑尺寸是 220px，所以 750px 的图片分辨率已经绰绰有余。如果图片格式支持 WebP，优先用 WebP，体积能比 JPEG 再小 30% 左右。

另外，小程序端的图片加载需要容错处理。我在 loadImages 里对每张图片都加了 onerror 分支，加载失败时给一张灰色占位底色，而不是让整个页面白屏。这样用户即使在弱网环境下打开活动页，至少能看到卡片框架和文字，体验不会完全崩溃。

5.2 渲染性能的三个关键处理

网页端的 CSS 3D 方案，我做了三件事来保证帧率稳定：

第一，给卡片加 will-change: transform，并确保 stage 在动画期间不触发 layout 重排。第二，用 translateZ(0) 或者 will-change 让浏览器把卡片合成到独立图层，避免每帧都重新计算图层树。第三，不要在动画循环里频繁读取元素的 offsetWidth、offsetHeight 这类强制同步布局属性，需要缓存的值在初始化时就存好。

Canvas 2D 方案，我用了三个手段：

第一，控制绘制帧率。如果走马灯不是持续的 60fps 动画，可以在用户停止交互后只保留惯性动画，等完全静止就不需要再 requestAnimationFrame 了，直接停掉循环，降低 CPU 占用。第二，离屏缓存。如果卡片内容比较复杂，例如包含多张图片和文字，可以先画到一个离屏 canvas 上，主循环只负责 drawImage 整张缓存，减少重复绘制。第三，避免在 render 函数里创建对象。第 4.3 节的代码里每次 render 都会创建新的 items 数组和对象，这在性能敏感场景可以改成预先分配数组并复用。

5.3 真机调试的“开发工具没问题，真机卡顿”问题

小程序最折磨人的是：开发工具里模拟器帧率很稳，一到真机就掉帧。我排查这类问题的顺序是：

先看是不是图片问题，把远程图片换成本地小尺寸图片测试，如果流畅了就是图片资源问题；再看是不是 Canvas 区域过大，把 canvas 的宽高降下来测试，如果流畅了就是绘制面积问题；最后看是不是 setData 过度调用，检查是否在主循环里调用了 this.setData，如果有就改成只初始化时 setData，动画数据用实例属性保存。

真机上还有一个容易忽略的地方：iOS 和 Android 对 canvas 的渲染性能差异很大，同一段代码可能 iOS 很流畅而 Android 中端机卡顿。我建议优先保证卡片数量不超过 10 张，绘制时避免使用 shadowBlur 这类高开销 API，阴影效果改成用卡片底部的纯色渐变模拟。

5.4 两端体验细节对齐

网页端可以使用鼠标 hover 效果，小程序端触摸设备没有 hover 概念，所以两端交互统一设计成“拖动浏览 + 点击查看”，不要依赖 hover。网页端的点击事件要区分拖拽和点击，和 4.4 节的 touch 判定逻辑一样，否则用户拖完卡片也会触发跳转。

弹层、loading、分享这些业务组件在两端也有一致性问题。我的做法是定义一套统一的事件模型：卡片点击后，不直接在组件里跳转，而是抛出一个 cardTap 事件，由外层页面决定是打开一个详情弹层还是跳转到小程序的哪个页面。网页端用自定义事件，小程序端用 triggerEvent，两端的业务代码不会互相污染。

6. 实操中的坑与解决记录：把走过的弯路一次性讲完

6.1 perspective 放错层级导致卡片透视扭曲

我在初版网页实现里，把 perspective 直接写在了 stage 上，结果卡片倾斜的时候，两侧明显出现一种“被拗弯”的扭曲感。后来排查发现，perspective 应该放在最外层的 .carousel 容器上，stage 只负责 preserve-3d。原因在于 perspective 定义了观察者到 3D 舞台的距离，如果放在每个子元素共同组成的 stage 上，浏览器会以 stage 自身为视点重新解释每个子元素的空间关系，导致透视基准混乱。

这个坑很隐蔽，因为放错层级之后效果看起来“好像也是 3D”，但仔细看会觉得透视不自然。如果你发现卡片边缘像被拉伸了，第一反应就检查 perspective 的位置。

6.2 小程序 touchmove 与页面滚动手势冲突

小程序页面如果本身可以上下滑动，canvas 上的左右滑动很容易被系统判定为滚动手势，导致旋转非常不跟手。我在第一个版本里用的是 bindtouchmove，结果真机上左右滑动时页面会跟着上下抖，体验很差。

解决办法：在 canvas 的 WXML 上使用 catchtouchmove，这个写法的含义是“捕获 touchmove 事件并阻止冒泡”，可以阻止页面滚动争抢手势。同时，在 onTouchMove 里加一个方向判断：如果横向位移小于纵向位移，就不更新旋转角度，把手势让给页面纵向滚动。

6.3 卡片数量动态变化时半径突变

活动页面经常会出现“今天有 8 个奖品、明天只剩 4 个”的情况。如果完全按照公式计算，卡片数量从 8 张变成 4 张时，半径会突然变大，视觉上整个圆柱像被充气了一样，非常突兀。

我的处理方式是：固定一个最大显示数量，比如 8。如果数据不足 8 张，用空白的占位卡片补齐到 8 张；如果数据超过 8 张，只渲染前 8 张，或者分页切换。这样半径始终不变，视觉不会跳动。另一种方案是给半径设置一个 clamp，让它只在一个小范围内浮动，但我更推荐占位卡片方案，因为实现简单且视觉稳定。

6.4 小程序 Canvas 远程图片不显示

这是小程序走马灯最容易翻车的点。如果你在开发工具里能看到图片，真机上却一片空白，首先检查下载合法域名配置。开发工具右上角“详情-本地设置”里能勾选“不校验合法域名”，但这只是开发时用的，真机上必须在小程序后台配置 downloadFile 合法域名。

还有一个坑：如果图片服务器开启了防盗链，小程序 canvas 加载时可能被服务器拒绝。解决办法是在 CDN 上关闭防盗链，或者给图片 URL 加上带签名的访问参数。

6.5 自定义导航栏与安全区高度适配

小程序页面如果用了自定义导航栏，canvas 的顶部位置不能用 0，否则会被状态栏遮挡。我通过 wx.getWindowInfo() 获取 statusBarHeight，再根据页面配置计算导航栏高度，把 canvas 的 top 设置成 statusBarHeight + 导航栏高度。底部同样要注意 safe-area 边距，iPhone 底部的小横条区域需要额外的 padding。

这个适配如果只做一次还好，但页面从普通导航栏切到自定义导航栏时，高度要重新计算，否则 canvas 就是残缺的。建议把这段逻辑封装成一个工具函数，所有页面共用。

6.6 获取用户信息的坑：头像昵称换成新能力

如果走马灯卡片的业务需要展示用户头像和昵称，比如“年度成就卡片”或者“排行榜卡片”，你会发现之前的 wx.getUserProfile 或者 open-type="getUserInfo" 方式，现在拿到的头像变成了灰色默认头像，昵称统一显示成“微信用户”。这个问题对应的就是很多团队遇到的“小程序获取登录后的微信用户失败”报错。

正确的做法是改用头像昵称填写能力：头像用 button 的 open-type="chooseAvatar" 让用户主动选择，昵称用 input 的 type="nickname" 让用户填写。获取完用户信息后，再通过后台接口或者云函数换算成业务需要的 openid，不要依赖旧的 getUserInfo。这个变化虽然没有影响 3D 走马灯本身的实现，但提醒我在做小程序组件时，一定要先确认依赖的用户能力是否还有效，否则卡片渲染好了，数据结构却拿不到。

做完这个小项目，最大的体会是：3D 走马灯这类效果的难点从来不在“让它转起来”，而在“让它在不同端、不同真机上都能稳定流畅地转起来”。网页端 CSS 3D 足够惊艳，小程序端 Canvas 2D 反而更可控。个人建议先把几何公式和数据结构设计好，再动手写渲染代码，最后再调惯性参数和图片质量，这样能少走很多弯路。文章里的代码片段都是按实际可运行的程度写的，新项目直接拷贝改造就可以了。