stb_image_write.h可一行写png，但要求rgba顺序、线性内存及正确stride；需定义stb_image_write_implementation、传入正height、stride等于行字节差，避免预乘alpha导致全黑。
用 stb_image_write.h 一行代码就能写 PNG，但 RGBA 顺序和内存布局必须对齐
直接结论：C++ 没有标准库支持 PNG 编码，得靠第三方单头库，stb_image_write.h 是最轻量、最常用的选择。它不依赖外部链接，编译零成本，但默认只接受 RGB 或 RGBA 连续排列的线性内存——如果你的数据是行首对齐（如某些 GPU 映射或 OpenCV 输出），或者 alpha 在前（ARGB），会直接生成错色或全黑图。
实操建议：
- 确保你的
data是从左到右、从上到下、每像素 4 字节、顺序为 R-G-B-A 的uint8_t*指针； - 调用前定义
#define STB_IMAGE_WRITE_IMPLEMENTATION且只在一个 .cpp 文件中包含该头文件，否则重复定义符号； - 宽度必须是正整数，高度为负数表示从上到下存储（
stb默认从下到上，即 OpenGL 风格），若你数据是常规图像坐标（顶行第一），传入正的height即可； - 示例：
#define STB_IMAGE_WRITE_IMPLEMENTATION #include "stb_image_write.h" <p>// 假设 data 指向 width×height×4 字节的 RGBA 数据，顶行在前 stbi_write_png("out.png", width, height, 4, data, width * 4);</p>
stbi_write_png 的 stride 参数容易被忽略，填错就只保存第一行或崩溃
第 5 个参数 stride_in_bytes 不是“每行字节数”的直觉值，而是“相邻两行起始地址的字节差”。多数情况下等于 width * 4，但如果你做了内存对齐（比如强制按 16 字节对齐每行），实际 stride 就大于这个值。填小了会导致后续行数据被截断，填大了会在行间读到脏内存，轻则 PNG 解析失败，重则触发 ASan 报 heap-buffer-overflow。
常见场景判断：
- 用
new uint8_t[width * height * 4]分配 → stride =width * 4； - OpenCV 的
cv::Mat（类型为CV_8UC4）→ stride =mat.step[0]，不是mat.cols * 4； - 使用
_aligned_malloc或 Vulkan 映射内存 → 必须用实际分配时的 pitch，不能硬算； - 不确定？用调试器看
data + width * 4和data + stride是否指向同一地址。
Alpha 通道为 0 时 PNG 看起来全黑？检查是否误用了预乘 Alpha
stb_image_write 不做颜色空间转换，也不处理 Alpha 预乘（premultiplied）。如果你的 RGBA 数据中 R/G/B 值已经乘过 A（例如从 WebGL 读回的 RGBA4444 或某些合成结果），而你又按普通非预乘方式写入，那么 A=0 的像素 R=G=B=0，A>0 但 R/G/B 被压低，最终图像发灰或局部死黑。
验证与修复：
- 临时把所有 A 强制设为 255：
for (int i = 3; i ，再保存——如果图像变正常，说明原始数据是预乘格式； - 非预乘转预乘（需浮点中间计算）：
r = r * a / 255;，注意整数除法截断，建议用uint16_t防溢出； - 更稳妥的做法：改用
libpng手动控制PNG_COLOR_TYPE_RGB_ALPHA和PNG_INTERLACE_NONE，并显式设置png_set_alpha_mode； - 简单项目别折腾——统一用非预乘 RGBA，R/G/B 值独立于 A 存储，这是绝大多数图像工具（Photoshop、GIMP）的默认行为。
Windows 下中文路径写入失败？不是编码问题，是 fopen 不支持 UTF-8
stb_image_write.h 底层用 fopen(filename, "wb")，而 Windows 的 MSVC CRT 默认把传入的 UTF-8 字符串当本地 ANSI（如 GBK）解码，导致含中文路径时返回 NULL，stbi_write_png 直接返回 0 并静默失败。
绕过方法（无需改库）：
- Linux/macOS 无此问题，UTF-8 路径天然支持；
- Windows 下先用
std::filesystem::u8path+std::ofstream以二进制打开文件，获取FILE*（需_fdopen+_open_osfhandle），但太重； - 最简方案：把输出目录固定为英文路径（如
"./output/"），文件名用时间戳或哈希，避开路径编码问题； - 真要支持中文路径？换
lodepng库，它提供lodepng_encode_file接口，内部用CreateFileW，原生支持 UTF-16 路径。
真正卡住人的往往不是“怎么写”，而是“为什么写了却看不到图”——多一半情况是 stride 算错、RGBA 顺序反了、或者 alpha 被悄悄预乘了。动手前，先用十六进制编辑器打开生成的 PNG，看开头是不是 89 50 4E 47，如果不是，说明根本没写进去；如果是，但图像异常，就回头查内存布局。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
