正确初始化需在唯一.cpp文件顶部先定义#define STB_IMAGE_WRITE_IMPLEMENTATION再#include "stb_image_write.h"，其余文件仅包含头文件；调用stbi_write_png时须确保filename有效、w/h>0、data非空、comp匹配通道数、stride准确，否则易崩溃或图像异常。
stb_image_write.h 怎么正确初始化和包含
必须在定义 STB_IMAGE_WRITE_IMPLEMENTATION 之前包含头文件，且只能在一个 .cpp 文件中定义一次。否则链接时会报重复符号错误（multiple definition of 'stbi_write_png'）。
常见错误写法：在头文件里加 #define STB_IMAGE_WRITE_IMPLEMENTATION，或在多个 .cpp 中重复定义。
- 在某个 .cpp 文件顶部（如
main.cpp）先写：#define STB_IMAGE_WRITE_IMPLEMENTATION #include "stb_image_write.h"
- 其他文件只需
#include "stb_image_write.h"（不带 define） - 确保头文件路径正确——如果用的是第三方目录，比如
third_party/stb/stb_image_write.h，路径就得写全
stbi_write_png 参数怎么填才不崩溃
stbi_write_png 崩溃最常见原因是传了空指针、宽高为 0、或像素内存布局不匹配。它不负责分配内存，只按你给的指针和 stride 读取数据。
关键参数顺序是：stbi_write_png(const char* filename, int w, int h, int comp, const void* data, int stride_in_bytes)
立即学习“C++免费学习笔记（深入）”；
-
w和h必须 > 0；PNG 不支持负尺寸或零尺寸 -
comp是通道数：1（灰度）、3（RGB）、4（RGBA）——必须和你的data实际通道一致，否则写出来颜色错乱或崩溃 -
data指针不能为nullptr，且需保证至少有w * h * comp字节有效内存 -
stride_in_bytes是每行字节数；若等于w * comp（紧密排列），直接传该值；若用了 padding（比如某些 OpenGL 读取结果），必须传真实 stride，否则图像上下颠倒或错行
示例（保存一个纯红色 2x2 RGB 图像）：
unsigned char pixels[2 * 2 * 3] = {
255,0,0, 255,0,0,
255,0,0, 255,0,0
};
stbi_write_png("red.png", 2, 2, 3, pixels, 2 * 3);
为什么保存出来的 PNG 是黑的或颜色反了
stb_image_write 默认按「顶行在前」（即内存里第 0 行对应图像顶部）写入，但很多图像 API（如 OpenGL 的 glReadPixels）默认返回「底行在前」。直接写会导致图像垂直翻转，看着像黑块（尤其当内容集中在底部时）。
- 检查数据来源：如果是
glReadPixels，记得手动翻转 y 轴，或用stbi_flip_vertically_on_write(1)启用自动翻转（仅对后续的写入生效） - 确认通道顺序：stb_image_write 期望 RGB 或 RGBA，不是 BGR；OpenCV 默认是 BGR，直接传会偏色——要么预处理转换，要么用
cv::cvtColor(img, img, cv::COLOR_BGR2RGB) - 注意数据类型：它只接受
unsigned char*；传float*或uint16_t*会解释成错误字节，结果不可预测
保存失败时怎么定位问题
stbi_write_png 返回 0 表示失败，但不提供具体原因。需要靠前置检查和 errno 辅助诊断。
- 调用前检查：
access(filename, W_OK) == 0（目标目录是否可写）、data != nullptr、w > 0 && h > 0 - 写入后立即检查 errno（Linux/macOS）或
GetLastError()（Windows），常见原因：磁盘满、路径含非法字符、父目录不存在 - 临时改用
stbi_write_png_to_func写到内存 buffer，排除文件系统干扰，验证数据本身是否合法
容易被忽略的一点：stb_image_write 不支持中文路径（即使系统 locale 正确），Windows 下用宽字符路径需自己转 UTF-8 再传入。
