Cocos Creator节点截图倒图？一文讲透Y轴翻转与图片保存流程

需求一句话：用户在游戏里点“分享”，我们把某个节点渲染成一张图，保存到相册或者上传到服务器。听起来特别简单，但我第一次交付这个功能的时候就被测试打回：保存下来的图片整个是倒立的。从 Cocos 的节点截图到最终保存图片，中间差了关键一步——翻转 Y 轴。这个问题在 Creator 2.x 里会遇到，升级到 3.x 换了一套 API 之后还会遇到，而且在浏览器调试和手机真机上表现还可能不一样。如果你也正在做分享图、头像裁剪、成就卡片生成这类功能，这篇文章应该能帮你少走大半天弯路。

我不打算只丢一个“把节点 scaleY 设为 -1”的偏方，那只是其中一条路，而且坑很多。我会把倒图产生的底层原因拆开讲清楚，再给出几条不同的翻转方案和适用场景，最后把我实际项目里稳定跑通的完整截图流程贴出来。涉及坐标、纹理、像素数组这些概念，我会尽量用大白话讲明白，代码以 Cocos Creator 2.x/3.x 的 TypeScript 风格为主，具体 API 名称在不同版本有差异，各位对着自己项目微调就行。

1. 先搞懂根因：节点截图为什么存成了倒图

1.1 渲染坐标系和图片文件编码坐标系根本对不上

先说结论：这不是 Cocos 的 Bug，而是渲染管线和图片编码器之间缺少了一次“翻面”。

我们调用节点截图，本质上发生的是这么一条数据流：节点被渲染进一张 RenderTexture，这张纹理在 GPU 里是一块显存；然后引擎把纹理的像素数据读回到 CPU 内存，也就是一个 Uint8Array 之类的字节数组；最后这个字节数组交给图片编码器，写成 PNG 或 JPG 文件。

问题就出在第二步到第三步的衔接上。WebGL / OpenGL 这类图形 API 的默认纹理坐标系，原点在左下角，也就是纹理的第一行数据对应的是画面的最底部。而 PNG、JPG 这类图片格式在编码时，文件里的第一行像素代表的是画面的最顶部，从上往下逐行扫描。GPU 侧觉得“第一行是下边”，图片编码器觉得“第一行是上边”，两边都没错，但中间没有人做 Y 轴翻转，最后保存出来的图自然就是上下颠倒的。

1.2 为什么在游戏屏幕上看着正常，存出来就“倒头睡”

你可能会问：那屏幕上为什么一切正常？因为引擎在最终上屏的时候，会有一套完整的视口变换和投影矩阵来处理这种差异，UI 显示层面对玩家是透明的。可当我们直接抓取 RenderTexture 里的裸像素数据去编码图片时，绕过了引擎那套用于上屏的变换，坐标系打架的问题就暴露出来了。

生活里有个很好懂的类比：假设货架上的商品从地板往上编号为 1、2、3、4，但快递单必须从最上面一栏往下填。你把编号 1 的商品名字填在快递单第一栏，结果就是最底下的商品出现在单子最顶上——所有东西都上下颠倒了。

1.3 “翻转 Y 轴”具体翻的是什么

很多人一看到“翻转 Y 轴”就想到把节点的缩放改成 (1, -1)，这确实是一种物理层面的翻转。但更本质的做法，是在拿到像素数组之后，把数组的每一行按照“第一行和最后一行互换、第二行和倒数第二行互换”的规则重新排列。前者是改渲染输入，后者是改输出数据。两条路都能解决倒图，但适用场景和副作用差别很大，这也是下一章要展开讲的核心。

2. 三条翻转路线：scale、逐行像素翻转和引擎内置 flipY

2.1 最简单的做法：渲染前把节点 scaleY 设为 -1

先说最容易上手、也最容易理解的一条路：在把目标节点渲染进 RenderTexture 之前，临时把节点的 scaleY 改成 -1，渲染完再恢复成 1。

以 Creator 里常见的写法为例，思路大概是这样的：

private captureNode(node: Node) { node.setScale(1, -1, 1); // 这里执行 RenderTexture 渲染 // renderTexture.render(node, camera); node.setScale(1, 1, 1); }

这样做的好处是改动量极小，不需要碰任何像素数据，对渲染流程没有侵入。但它有一个非常致命的副作用：scaleY 为 -1 的时候，节点里所有内容都会被垂直镜像。中文字、英文字母、图标、UI 纹理里的方向性符号全部会倒过来。如果你的截图里包含用户昵称、功能介绍文字、按钮标识这类信息，这种方法会让最终图片里的文字变成倒着的，等于从“图片倒立”变成了“图片内容倒立”，根本没法交付。

所以这个方法只适合纯纹理、纯图形、不含可读文字的简单节点。真要这么干，还有个小细节：最好是在一个临时父节点上做 scale，而不是直接改业务节点自身的 scale，不然触发到子节点的 Layout 重排或者 Tween 动画，恢复的时候容易出幺蛾子。

2.2 最通用的做法：拿到像素数组后逐行对调

既然 scale 方案会影响内容可读性，那更稳的做法就是不动渲染，只修数据。思路是把读到的 RGBA 像素数组按行前后互换。

下面是一个可以直接抄的 TypeScript 函数：

function flipImageY(pixels: Uint8Array, width: number, height: number) { const bytesPerRow = width * 4; // RGBA，每个像素 4 字节 const tempRow = new Uint8Array(bytesPerRow); for (let y = 0; y < Math.floor(height / 2); y++) { const topStart = y * bytesPerRow; const bottomStart = (height - 1 - y) * bytesPerRow; // 保存顶部一行 tempRow.set(pixels.subarray(topStart, topStart + bytesPerRow)); // 底部行搬到顶部 pixels.copyWithin(topStart, bottomStart, bottomStart + bytesPerRow); // 原顶部行搬到底部 pixels.set(tempRow, bottomStart); } }

这个函数的逻辑和“把一摞纸上下翻转后重新整理”一样：第 0 行和第 height - 1 行互换，第 1 行和倒数第 2 行互换……只换一半，因为换完一半之后后半行也已经归位了。

性能方面完全不用担心。对一张 2048 x 2048 的图，height 是 2048，实际循环只需要做 1024 次行互换，每次操作一行 8KB 的数据，在移动端耗时也就是几十毫秒的量级，而且是一次性开销，不会影响游戏帧率。

这个方法最稳的地方在于：它对渲染内容完全无感知。管你节点里是文字、粒子、Mesh、还是 Mask，只要像素数组被正确翻转，最终图片一定是正的。我目前绝大多数项目都用这条路线。

2.3 最省事的一种：查你的引擎版本有没有内置 flipY

在部分 Cocos Creator 3.x 版本里，RenderTexture 或者相关纹理创建接口提供了 flipY 相关的选项。原理是让引擎在把纹理数据从 GPU 侧交到 CPU 侧之前，先自动完成一次 Y 轴翻转。如果版本支持，代码里可能就是一行开关的事，省掉手动翻转函数。

但这里我必须提醒一句：这个 API 在不同小版本里的名字和可用性差异比较大，有的版本放在 RenderTexture 上，有的放在纹理描述符里，2.x 版本则基本没有开放。我不会给你写一个可能和你的项目版本对不上的 API 名。最靠谱的做法，是打开你当前引擎版本的 API 文档，搜索 RenderTexture 相关接口，看有没有类似 flipY 的属性或构造参数；如果没有，就回到 2.2 的手动翻转方案。

另外，即使引擎提供了 flipY，也要确认它翻转的到底是哪一段数据流。有的开关只影响采样时的 UV 坐标，并不会改变最终输出到图片文件的像素顺序，这种开关对保存图片是无效的。所以引入了开关之后，一定要用包含文字内容的节点做一次正反验证。

2.4 三条路线怎么选：一张对照表

我把三条路线的特性整理成表格，方便你按项目情况快速选择：

我的建议是：别把第一条路当默认方案，它太容易坑到自己。第二条路的翻转函数写一次，放在工具类里所有项目通用，最不挑环境。

3. 翻转解决了，图还是糊或黑：清晰度、透明底和截帧时机

3.1 RenderTexture 尺寸要按物理像素算，别拿设计分辨率硬顶

很多项目分享图发出来之后被吐槽“糊”，问题往往不在翻转，而在 RenderTexture 的尺寸设置。如果你在设计分辨率 720 x 1280 下做 UI，然后直接创建一个 720 x 1280 的 RenderTexture，在高分屏手机上保存出来的图片分辨率就偏低，放大会模糊。

正确的做法是考虑设备像素比（devicePixelRatio，简称 DPR）。比如 iPhone 的逻辑分辨率是 390 x 844，但物理像素是 1170 x 2532，DPR 是 3。如果节点实际显示区域是 300 x 400 逻辑像素，那 RenderTexture 的宽高至少要设置成 900 x 1200 物理像素，截图才会锐利。

设置 RT 尺寸时可以用节点内容尺寸乘以 DPR：

const scaleFactor = view.getScaleX(); // 在某些版本可以用 view.getDevicePixelRatio() const rtWidth = Math.floor(nodeSize.width * scaleFactor); const rtHeight = Math.floor(nodeSize.height * scaleFactor);

这里要特别留意：不同版本获取 DPR 的方式不一样，有的用view.getDevicePixelRatio()，有的用view.getScaleX()，你得对着当前版本的实际返回值测试一下。宁可多设置一些像素，也不要让截图比预期小。

3.2 透明通道丢了就是黑底：RGBA8888 和 clearFlags

做分享图片，尤其是海报、头像框这类需要异形显示的内容，透明背景是刚需。但很多人保存 PNG 出来发现背景是黑的，或者透明的地方变成了一块块的杂色，排查半天发现不是翻转问题，而是纹理格式和清屏色没有设置对。

首先要确保 RenderTexture 的颜色格式是带 alpha 通道的格式，最好是 RGBA8888。如果底层选择了不带透明度的格式，保存成 PNG 时透明信息根本不存在，黑底就会出现。

其次要检查渲染前的清屏行为。用 RenderTexture 渲染节点时，如果 clearFlags 设置不对，背景会被默认清成不透明的颜色。设置成清澈色即可：

renderTexture.clearFlags = RenderClearFlag.COLOR; renderTexture.clearColor = new Color(0, 0, 0, 0);

这里我再补一个实际经验：不要用 JPG 格式保存带透明的截图。JPG 本质上不支持透明通道，保存时引擎或平台库会把 alpha 强行压掉，背景一定会变成黑底或白底。要做透明背景分享图，必须用 PNG 格式。

3.3 截帧时机：动画没走完，截出来的图就缺胳膊少腿

这个问题很隐蔽。假如用户点了一下“生成海报”按钮，这时你才把海报节点的某些子节点内容更新完（比如设置了一个新的 Sprite 图片、把某个进度条动画播放开），紧接着在同一帧回调里立刻执行渲染和读取像素，截出来的往往是旧内容，或者是半透明过渡状态的画面。

原因是节点虽然更新了数据，但那一帧的渲染命令还没有被送到 GPU 执行，RenderTexture 里还是上一帧的像素内容。粒子、拖尾这一类需要多帧累计的视觉效果就更明显，第一帧根本来不及生成历史顶点数据。

常见解决办法是把截图动作延后一帧或几帧：

this.scheduleOnce(() => { // 渲染 RenderTexture 并保存图片 }, 0);

也可以监听导演的绘制结束事件，比如Director.EVENT_AFTER_DRAW之后再做截取。我的经验是：海报里如果有粒子或拖尾动画，等 2 到 3 帧再截，效果更稳定。

4. 节点截图实战里躲不掉的其它坑：合图、Mask、拖尾和跨端

4.1 目标节点还在动态合图里，图会被“抠坏”或错位

遇到一个怪现象：单独截某个小图标节点，保存出来的图片不是图标本身，而是附近某个图标的一部分，甚至图像完全错乱。十有八九是动态合图（Dynamic Atlas）在作怪。

Cocos Creator 为了减少 draw call，会把小图片在运行期动态合并进一张大纹理。如果你只是截取其中一个子节点的视觉内容，渲染时读取到的可能不是原图中的独立区域，而是合图里的某个小方块，Y 方向翻转之后更容易和别的区域串位。

处理方法一般有两种：要么在截图前把目标节点的纹理帧临时替换成非合图的独立纹理；要么在项目设置里对相关资源关闭动态合图。具体开关名称在不同版本里不一样，2.x 和 3.x 的项目设置里都能找到，建议打包之前先确认截图里有没有涉及这类小图标。

4.2 Mask 遮罩和 MotionStreak 粒子节点首帧残缺

如果你的截图目标节点挂着 Mask 组件，比如圆角头像框、圆形小地图，直接用 RenderTexture 渲染这个节点时，可能出现遮罩范围外部的内容也被画出来，或者遮罩区域整个空掉的情况。这是因为 Mask 依赖模板缓冲区（stencil buffer），RenderTexture 单独渲染时模板缓冲的处理逻辑和正常 Canvas 渲染并不完全一致。

我的建议是：不要试图在一个带 Mask 的复杂节点上直接做完美截图。先把要展示的内容平铺到一个临时节点树里，让截图节点保持简单的渲染层级，再在截图生成后用代码做一次矩形/圆形裁剪，或者直接把整个界面截下来再做二次处理。这样绕开模板缓冲的不可控性，稳定得多。

MotionStreak 和粒子系统是另一个容易缺内容的点。拖尾需要前几帧的历史位置信息，粒子系统第一帧往往还没发射出足够的粒子。如果你在节点激活后的第一帧就截图，拖尾和粒子当然只有一点点。我踩过这个坑之后，习惯在截图前手动让效果先跑两帧：

for (let i = 0; i < 3; i++) { director.tick(); // 示意，实际要看项目里如何手动推进帧 }

如果项目不允许手动 tick，也可以等待真实帧数过去，再执行截图。

4.3 浏览器调试正常、打包 APK 就翻车：真机才是最终标准

分享图功能做调试时，很多人习惯在浏览器里预览，用 Spector.js 这类 WebGL 调试工具看看纹理对不对。这些工具对游戏开发确实很有帮助，能直观看到 RenderTexture 在 GPU 里的样子、各个 attach 的纹理方向、材质参数等等，定位“图片到底是不是从某个环节开始倒的”很有效。

但我要特别强调一个容易让人崩溃的事实：浏览器里截图正常，打包成 APK 到安卓真机上保存，图片可能会倒；反过来也有可能。不同平台底层的 OpenGL 实现、引擎封装层的像素读取逻辑、甚至图片编码库对行序的处理，都可能存在差异。浏览器只是个模拟环境，永远不能替代真机验证。

所以在发布前，务必在安卓和 iOS 真机上各跑一次完整的“截图 -> 保存 -> 打开相册 -> 查看图片方向”流程。我把这个流程称之为“截图自测五连”：方向正不正、清晰度够不够、透明背景对不对、内容是否完整、文字是否可读。五连都过了，这个功能才真正算完成。

5. 我目前稳定在用的完整截图流程

5.1 一套可复制的 RenderTexture 截图流程

经历了各种花样翻车之后，我现在做节点截图基本固定一套流程，步骤比较好记：

1. 计算目标节点的物理像素尺寸，创建对应大小的 RenderTexture。
2. 把 RenderTexture 的清屏颜色设为全透明，确认格式为 RGBA8888。
3. 将目标节点渲染进 RenderTexture，如有粒子或拖尾则先等待若干帧。
4. 读取像素数据，得到 Uint8Array 数组。
5. 调用前面写的 flipImageY 函数，对像素数组做逐行翻转。
6. 把处理好的像素数据交给图片编码和保存模块，生成 PNG 并写入相册或上传。

核心代码框架大致是这样的：

const view = new RenderTexture(); view.reset({ width: rtWidth, height: rtHeight, format: Texture2D.PixelFormat.RGBA8888 }); const spriteFrame = new SpriteFrame(); spriteFrame.texture = view; // 渲染节点 view.render(targetNode, camera); // 读取像素 const pixels = view.readPixels(); // 翻转 Y 轴 flipImageY(pixels, rtWidth, rtHeight); // 编码保存（浏览器端可以转 canvas，原生端一般走平台插件） saveAsPng(pixels, rtWidth, rtHeight);

这里readPixels的返回值格式和接口细节在不同版本里有差异，有的还需要自己创建 ArrayBufferView 传入。你以当前版本的 API 为准，不要盲抄。

5.2 加一个“是否已翻转”开关，避免翻两次

有个特别尴尬的场景：某天你的同事升级了引擎版本，RenderTexture 内部已经自动处理了 Y 轴翻转，但你保留了旧代码里的手动翻转函数，结果所有分享图又变成倒的了——因为翻了两次等于没翻。

为避免这种问题，我会在截图工具类里放一个布尔开关：

let flipYEnabled = true;

第一次在某个平台上跑通后，如果确认图片方向正确，就把这个开关固定为当前值；如果引擎升级或迁移到新平台，先打开真机测试，看图片方向是否反了，再决定是否切换。这个开关看着不起眼，但能让你在不同版本、不同平台之间切换时少掉不少头发。

5.3 真机自测的路线图

最后说一个我自己的做法：每次写完截图逻辑，我不会先跑去调业务 UI，而是先拉一个最简单测试页面，页面上只有一张带中文文字的 Sprite 和一块纯色背景，然后跑完整的截图保存链路。文字会让“方向是否正常”一目了然——如果图片倒着，文字也是倒的；如果被镜像，文字也镜像。确认这张测试图正了，再接入真实业务节点，逐项检查粒子、Mask、动态合图这些复杂元素。

这套小测试页面特别值得做，因为截图功能涉及的变量太多：坐标系、纹理格式、像素密度、清屏色、渲染时机、平台差异……任何一个环节出错，最终表现可能都是“图片不对”，但原因差了十万八千里。先把环境变量压到最少，排查起来会轻松非常多。

我也见过有人把截图和保存的逻辑全塞在业务页面里，出了问题只能靠猜。几次踩坑之后你会发现，把截图功能抽成独立的工具类，再配一个可复现的最小测试场景，是性价比最高的做法。这个习惯帮我省下来的时间，比写功能本身的时间多得多。