freetype初始化失败主因是依赖缺失或链接错误；路径需utf-8编码且用正斜杠；渲染前须设字号，注意bitmap偏移与advance换算；资源释放须严格顺序，多线程需独立库实例。
FreeType 初始化失败：FT_Init_FreeType 返回非零值
多数人卡在第一步——FT_Init_FreeType 就失败，返回 -1 或其他负值。这不是字体文件问题，而是库没正确链接或运行时找不到依赖。
- Linux/macOS 下确认已安装
freetype2开发包（如 Ubuntu 的libfreetype6-dev），且链接时加了-lfreetype - Windows 上若用预编译 DLL，必须把
freetyped.dll（Debug）或freetype.dll（Release）放在可执行文件同目录，否则FT_Init_FreeType会静默失败 - 不要跳过返回值检查：
if (error) { fprintf(stderr, "FT_Init_FreeType failed: %d ", error); return -1; }
加载 TTF 文件后无法获取字形：FT_Load_Char 返回 FT_Err_Unknown_File_Format
这个错误名有误导性——实际往往不是格式问题，而是路径或编码惹的祸。
-
FT_New_Face的第二个参数是字体文件路径，C++ 字符串传入前必须是 UTF-8 编码（Windows 控制台默认是 GBK，直接传中文路径大概率失败） - 路径中避免使用反斜杠：
"C:\fonts\arial.ttf"要写成"C:/fonts/arial.ttf"或用原始字符串R"(C: ontsrial.ttf)" - 加载成功后记得调用
FT_Set_Pixel_Sizes(face, 0, 48)设置字号，否则后续FT_Load_Char可能返回 0 字形（face->glyph->bitmap为空）
渲染出的字形模糊或偏移：bitmap 宽高与 advance 不匹配
FreeType 默认返回的是单通道灰度 bitmap，但新手常直接 memcpy 到 RGBA 纹理里，结果发现文字发虚、位置飘移。
-
face->glyph->bitmap.width和face->glyph->bitmap.rows是 bitmap 实际尺寸，但字形绘制起点在(face->glyph->bitmap_left, face->glyph->bitmap_top)，不是左上角 -
face->glyph->advance.x是下一个字的水平偏移（单位是 1/64 像素），要右移 6 位才得像素值：int x_advance = face->glyph->advance.x >> 6; - 若用 OpenGL 渲染，
glPixelStorei(GL_UNPACK_ROW_LENGTH, 0)必须设对，否则 bitmap 行对齐错乱，字形被拉伸
内存泄漏和资源释放顺序：FT_Done_Face 之后再访问 face 成员
FreeType 的资源释放有严格顺序：先释放 glyph bitmap（如果手动分配过），再 FT_Done_Face，最后 FT_Done_FreeType。中间任意一步提前释放或重复释放都会 crash。
-
FT_Load_Char每次都会覆盖前一次的face->glyph，无需手动 free；但如果你用FT_Render_Glyph后又 malloc 了新 bitmap 缓存，就得自己free() -
FT_Done_Face会自动释放 face 内部所有 glyph 数据，所以千万别在FT_Done_Face之后还去读face->num_glyphs或face->glyph->bitmap.buffer - 多线程环境下，
FT_Library实例不能跨线程共享，每个线程应有自己的FT_Init_FreeType/FT_Done_FreeType配对
FreeType 的坑不在 API 多难懂，而在它把很多底层细节（比如 subpixel hinting、LCD 排列、kerning 表解析）全交给你处理。哪怕只是显示一行英文，FT_Load_Char 和 FT_Render_Glyph 之间那几行坐标计算，漏掉一个位移偏移，文字就糊成一片。别信“加载完就能用”，先拿一个 ASCII 字符跑通整个 pipeline，再谈换字体、加颜色、做动画。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
