简介Kylin环境下LibGdiPlus的安装与配置指南主要面向需要在国产操作系统中运行依赖Windows GDI图形接口应用的开发者、运维人员及测试人员。文档以清晰的分步流程从修改apt软件源地址如使用sudo pluma编辑sources.list开始依次讲解libtiff-dev、libjpeg-dev、libgif-dev依赖库的安装再介绍下载源码、解压、configure配置、make编译与make install安装的完整过程。针对安装中可能遇到的编译错误给出了将解压目录下.src/.libs中的库文件复制到/usr/lib的备用处理方法并补充了sudo ldconfig更新系统库路径、设置环境变量等验证与收尾步骤能帮助用户独立完成LibGdiPlus部署并解决典型问题。资源为单个docx文档共1个文件压缩包大小约807KB以文字步骤和命令示例为主便于随时查阅。目前已有571人学习下载内容完整且面向实操适合刚接触国产平台适配或正在为Kylin配置跨平台图形应用支持的读者参考。1. 在 Kylin 上装 libgdiplus.NET 程序部署到这里十有八九卡在这一步Kylin 上跑 .NET 程序的人十有八九在 libgdiplus 安装与配置上栽过跟头。最常见的一幕是程序在 Windows 上好好的部署到 Kylin 后一启动就报 DllNotFoundException或者 System.Drawing 相关的调用直接抛异常查半天发现是 gdiplus 这个原生库没装上、装错版本、或者装了没生效。这个标题看着简单背后其实牵扯到系统源、编译工具链、动态库路径、字体环境四件事任何一环断了程序就当面翻车。这篇按我在 Kylin 上处理这个库的实际顺序把概念、安装、配置和坑一次讲透适合正在把 Windows 桌面程序或老项目迁到 Kylin 的开发者照着操作。2. 先搞清楚 libgdiplus 是什么它和 Windows GDI 的差异决定了你的装法2.1 libgdiplus 补的是 .NET 的哪块缺.NET 程序里凡是用了 System.Drawing 命名空间——Bitmap、Graphics、Pen、Brush、Font、Image.Save——这套 API 在 Windows 上由系统自带的 GDI 实现对应的动态库叫 gdiplus.dll。Linux 上没有这套东西于是 Mono 生态用 C 语言基于 Cairo 图形库重写了一个兼容实现就是 libgdiplus编译产物是 libgdiplus.so。System.Drawing 的 P/Invoke 层按名字去找 gdiplus在 Linux 上实际映射到 libgdiplus.so所以这个库装不上、加载不了所有图形相关调用立刻全崩。很多入坑的人以为它是个可选组件其实对依赖 System.Drawing 的老程序来说它是硬依赖。我接手过某公司的一个老报表系统服务端大量使用 Graphics 画图表再导出图片迁到 Kylin 时没装 libgdiplus结果一启动就报找不到 gdiplus整个服务起不来。换句话说要不要装这个库不由你选择由你的代码用没用 System.Drawing 决定。识别方法很简单源码里搜一下 using System.Drawing 或者 System.Drawing.Common 的引用有就绕不开它。2.2 安装前先确认三件事系统版本、CPU 架构、软件源我一般动手前先执行三条命令把环境摸清楚避免装完才发现架构或源不匹配cat /etc/os-release uname -m apt-cache policy libgdipluscat /etc/os-release 看 Kylin 的版本号。Kylin 的软件源基于 Debian 系基线不同版本能拿到的包不一样版本号直接决定你走 apt 还是走源码编译。uname -m 确认 CPU 架构。x86_64 和 aarch64ARM64在 Kylin 服务器版和桌面版上都很常见。装错架构的 .so程序加载时照样报错而且报错信息不会直接告诉你架构不对只会说找不到库容易被带偏。apt-cache policy libgdiplus 是最关键的一条。源里有这个包会直接显示候选版本号什么都不显示说明当前源里没有得考虑加源或源码编译也就是第四章的路径。注意 apt-cache policy 显示的是源里的版本不是已安装的版本。已安装版本要看 dpkg -l libgdiplus。两者不一样排查时别弄混。我见过有人看到 policy 有输出就以为装好了结果程序还是报错最后发现根本没装。2.3 运行时决定安装方式Mono 还是 .NETKylin 上跑 System.Drawing 代码的人实际分两拨。一拨是老人老项目还在用 Mono 运行时mcs 编译出 exe 后用 mono 命令跑这种场景下 libgdiplus 版本最好和 Mono 配套避免绘制行为不一致。另一拨已经切到 .NET 6 及以上用 dotnet 命令跑这时 libgdiplus 只需要提供 gdiplus 的 P/Invoke 入口即可版本要求宽松些但要额外注意 .NET 6 以后 System.Drawing.Common 在非 Windows 平台默认禁用细节放到第五章踩坑清单里细说。判断自己属于哪一拨两条命令mono --version dotnet --info哪条有输出说明机器上装的是哪个运行时都没输出说明程序根本没部署到这个环境先装运行时再回来折腾 libgdiplus。如果是帮别人排查一台完全陌生的机器我一般先跑这两条再决定后续命令的写法省得按错误路线白查半天。3. 用 apt 装 libgdiplus最快路径与版本订选3.1 一条命令装完依赖让系统自己拉如果 Kylin 的软件源配置正常且 libgdiplus 在源里apt 安装是最省事的路径sudo apt update sudo apt install -y libgdiplus执行完顺便确认实际装了什么尤其是关联的图形库dpkg -l | grep -E libgdiplus|cairoapt 会自动把 libcairo2、libjpeg、libgif、libtiff、libpng、freetype 这些依赖一起拉进来这就是包管理器的价值依赖树不用自己盯。注意 apt 装出来的 libgdiplus.so 一般位于 /usr/lib/x86_64-linux-gnu/ 或 /usr/lib/aarch64-linux-gnu/ 下具体路径以 dpkg -L 为准这个路径后面排查时会用到。参数说明-y 表示跳过安装确认脚本化部署时必加。apt update 之前先确认源里能正常解析 Kylin 的仓库否则 update 阶段就报 404后面怎么装都白搭。我在某台服务器上遇到过源列表里残留了旧系统版本的地址apt update 一直报错处理方式是先修正 /etc/apt/sources.list 里的地址再回来装。3.2 装完立刻做三件事验证ldconfig 缓存、so 文件、运行时很多同事装完 libgdiplus 就直接跑程序报错后回头怀疑到底装没装上。我习惯装完马上做三条命令ldconfig -p | grep gdiplus dpkg -L libgdiplus | grep \.so mono --versionldconfig -p | grep gdiplus确认动态库缓存里能看到 libgdiplus。看不到程序运行时 ld.so 找不到它就会出现典型的 DllNotFoundException。dpkg -L libgdiplus | grep .so列出这个包实际安装的文件确认 so 文件的真实路径。不同架构路径不一样记住它后面排查时对照着看。mono --version如果走 Mono 路线这条顺带确认运行时是否正常。Mono 启动时对 libgdiplus 有隐式依赖Mono 能起来说明环境至少没大问题。如果是 dotnet 环境换成 dotnet --info 即可。3.3 源里没有先别急按顺序试这三条路如果 apt-cache policy libgdiplus 没有输出先别一头扎进源码编译。我一般按这个顺序尝试确认 sources.list 里是不是只开了主源。有些 Kylin 版本默认没开完整归档把相关源打开后 apt update 再看一次可能就有包了。从同源系归档里直接下载 .deb 安装。风险是依赖版本可能对不上apt 装的时候可能报依赖冲突能用但心里要有数。如果机器装了 Mono 的官方源优先试它提供的 libgdiplus 包。Mono 源里的版本通常和 Mono 运行时配套适合 Mono 用户。这三条都走不通才进入第四章源码编译。另外即使源里有包如果版本明显落后于你的 Mono 运行时我也会选源码装一个指定版本避免因 API 行为不一致导致绘制结果诡异。4. 从源码编译安装 libgdiplus源里没有时的兜底方案4.1 编译依赖清单少一个 configure 就失败源码编译 libgdiplus 最难受的不是编译本身而是依赖。configure 阶段缺一个开发包就当场报错。我在这类机器上常用的依赖安装命令如下sudo apt install -y build-essential autoconf automake libtool \ pkg-config libglib2.0-dev libcairo2-dev \ libjpeg-dev libgif-dev libtiff-dev libpng-dev \ libfontconfig1-dev libfreetype6-dev libx11-dev逐项说明build-essential 提供 gcc 和 makeautoconf、automake、libtool 是 autotools 工具链libgdiplus 的构建系统靠它们生成 configure 脚本pkg-config 用于在 configure 阶段探测依赖库libglib2.0-dev 提供 GLib 类型系统libgdiplus 底层数据结构依赖它libcairo2-dev 是核心libgdiplus 本质上是包在 Cairo 上的一层 GDI 兼容层jpeg、gif、tiff、png 四个开发包对应图像编解码器缺哪个System.Drawing 里对应格式的编解码就失败fontconfig 和 freetype 负责字体管理与文字渲染中文场景下直接影响文字能否正常绘制libx11-dev 是 X11 客户端库部分绘制路径会用到。这里有个常见坑某些 Kylin 最小化安装里 Cairo 相关库版本偏旧libgdiplus 新版本要求更高configure 时会报 cairo version too old。这种情况优先看源里有没有更新的 libcairo2-dev没有的话我一般先试装旧版 libgdiplus 而不是去源码编译 Cairo因为 Cairo 牵连更广为它趟浑水不值当。4.2 configure、make、install 三步与常见报错依赖齐了之后编译安装本身是标准三步git clone https://github.com/mono/libgdiplus cd libgdiplus ./autogen.sh --prefix/usr/local make -j4 sudo make installgit clone 从官方仓库拉源码到本地。网络正常时一般几十秒到几分钟看仓库大小。./autogen.sh --prefix/usr/localautogen 会先调用 autotools 生成 configure 脚本再自动执行--prefix 指定安装目录。我习惯用 /usr/local和系统包管理安装的文件分开来源清楚日后卸载也方便。make -j4-j4 表示 4 个并行编译任务机器核多的调成 -j8 能快不少。sudo make install把编译产物复制到 /usr/local/lib 下。configure 阶段最常见的报错是缺头文件报错信息里会明确写 missing xxx.h。看到这种直接 sudo apt install xxx-dev 补上再重新 autogen。另一个容易遇到的是提示文件行尾符异常或 /bin/bash^M这种通常是源码在 Windows 上解压过导致换行符被改重新在 Linux 上 clone 一遍即可别手动去改文件改了也容易遗漏。4.3 装完必须做的链接配置ldconfig 不跑等于白装源码装到 /usr/local/lib 之后系统动态库加载器默认不一定搜这个目录。很多人卡在这一步make install 明明成功了程序还是报找不到 gdiplus。原因就是 ldconfig 不知道新库存在。正确做法是把它加进装载器搜索路径echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/libgdiplus.conf sudo ldconfig ldconfig -p | grep gdiplustee 把 /usr/local/lib 写进 /etc/ld.so.conf.d/libgdiplus.confldconfig 重新生成缓存最后一条 grep 能看到 libgdiplus.so 才算数。如果你不想动系统级配置也可以 export LD_LIBRARY_PATH/usr/local/lib:$LD_LIBRARY_PATH但这种方式只对当前终端会话有效程序以服务方式启动时容易漏掉生产环境不推荐。提示如果程序是 dotnet 跑的个别情况下还要检查运行时相关的环境变量是否覆盖了库搜索路径。一般 ldconfig 做完就够但确认一下没有坏处。5. libgdiplus 装完后的常见问题排查四个坑的现象、原因、解决5.1 明明装好了程序还是报找不到 gdiplus现象libgdiplus 已安装ldconfig -p 也能查到但 .NET 程序启动时抛 System.DllNotFoundException: gdiplus.dll。原因主要有三种。第一种是 ldconfig 缓存确实没更新程序跑在另一个终端或服务进程里该进程启动时库路径还没写入缓存。第二种是 32 位程序在 64 位系统上找 32 位的 libgdiplus而系统只装了 64 位库。第三种是程序自带的 native 库搜索配置绕过了系统默认路径。解决先 file 看程序二进制和 so 文件的架构确认位数匹配再 ldd 看运行时能否解析到 libgdiplus。最直接的办法是在同一终端里执行 ldconfig 后重新起程序。我遇到过某公司的服务脚本在别处覆盖了 LD_LIBRARY_PATH把系统路径挤掉了去掉那个 export 后问题消失。这类问题最容易玄学化实际八成是搜索路径被覆盖。5.2 中文文字全部画成方块现象程序能运行英文数字正常但 DrawString 画出来的中文是整排豆腐块。原因不是 libgdiplus 的问题是系统里没有可用的中文字体。libgdiplus 通过 fontconfig 找字体字体列表里没有 CJK 字体时它只能用西文字体渲染中文结果就是方块。解决装一个中文字体再刷新字体缓存sudo apt install -y fonts-noto-cjk sudo fc-cache -fv然后 fc-list :langzh 确认系统里已有中文字体。这解释了为什么同一套程序在 Windows 上正常、到 Kylin 上文字全方块Windows 自带中文语言包和字体Linux 服务器版往往不预装 CJK 字体新部署的机器重点检查这一步。5.3 .NET 6 之后 System.Drawing.Common 直接报平台不支持现象用 .NET 6 或更高版在 Kylin 上跑程序一碰 System.Drawing 就抛 PlatformNotSupportedExceptionlibgdiplus 装得好好的也没用。原因从 .NET 6 开始System.Drawing.Common 默认只在 Windows 平台启用非 Windows 上运行时默认禁用这个行为由运行配置里的 System.Drawing.EnableUnixSupport 控制默认关闭。解决在项目文件里加一个运行时配置项ItemGroup RuntimeHostConfigurationOption IncludeSystem.Drawing.EnableUnixSupport Valuetrue / /ItemGroup重新发布部署。注意这只是过渡开关官方并不推荐在服务端长期依赖 System.Drawing性能和稳定性都不如专用图像库。短期迁动能跑长期建议评估换 SkiaSharp 或 ImageSharp 这类跨平台方案。5.4 保存图片时抛 ExternalException 或图片内容损坏现象DrawString 正常但 Bitmap.Save 要么抛 System.Runtime.InteropServices.ExternalException要么保存出来的图片颜色错乱、文件打不开。原因libgdiplus 保存图片时依赖对应编码器库。保存 PNG 要 libpngJPEG 要 libjpegGIF 要 libgif。编译时没带上某个库或系统里对应库版本太旧保存就会失败或损坏。另一个诱因是 Cairo 和 libgdiplus 版本差异过大图形上下文操作异常。解决先确认编译时依赖的编解码库是否齐全dpkg -l 检查 libpng、libjpeg、libgif 等缺哪个装哪个然后重新编译 libgdiplus。依赖齐全还出问题就换 libgdiplus 版本我遇到过旧版配新 Cairo 出错换成匹配版本后保存恢复正常。血泪经验这种问题先看编码器库别看业务代码业务代码无辜得很。6. 配置到能出图之后最小验证程序、字体缓存与句柄习惯6.1 一个最小 C# 程序验证绘制、字体、保存全链路我每次装完 libgdiplus不直接拿业务程序去试先跑一个最小验证程序把创建画布、画文字、保存图片整条链路单独测一遍using System; using System.Drawing; using System.Drawing.Imaging; class GdiplusTest { static void Main() { using (var bmp new Bitmap(800, 600)) using (var g Graphics.FromImage(bmp)) { g.Clear(Color.White); g.DrawString(Kylin libgdiplus OK 中文测试, new Font(Noto Sans CJK SC, 18), Brushes.Red, 20, 20); bmp.Save(/tmp/gdiplus_test.png, ImageFormat.Png); } Console.WriteLine(PASS); } }保存为 gdiplus_test.cs用 Mono 编译运行时这样执行mcs gdiplus_test.cs -r:System.Drawing.dll -out:gdiplus_test.exe mono gdiplus_test.exe输出 PASS 后打开 /tmp/gdiplus_test.png 看两点图片能正常打开编码器工作正常中文没有变方块字体链路正常。如果机器上 mcs 不存在说明缺 Mono 编译工具装 mono-devel 后再试。用 .NET SDK 的话dotnet new console 建工程跑同一段代码效果一样。这个程序成本极低能把八成环境问题挡在业务程序之前。6.2 字体注册与缓存刷新中文环境里必做的收尾libgdiplus 不直接读 /usr/share/fonts 下的字体文件而是通过 fontconfig 查询。所以手动拷了字体文件进系统后必须执行 fc-cache -fv 刷新缓存否则程序找不到新装字体。这解释了一个常见迷惑Kylin 上装了中文字体还是方块字体文件在缓存没刷fontconfig 感知不到。我习惯把这条命令写进部署脚本和 libgdiplus 装在一起装完顺手验证fc-list :langzh | head -20能输出中文字体列表字体链路就是通的。别省略这步字体问题比库问题更难肉眼排查等业务跑起来发现图片里全是方块再回头浪费的时间够装三遍库。6.3 一个容易被忽略的老毛病GDI 对象的释放习惯最后说一个跟配置无关但十个排查里八个会遇到的隐患——GDI 对象不释放。System.Drawing 的 Bitmap、Graphics、Pen、Brush 都实现了 IDisposable不释放的话 libgdiplus 底层的原生资源持续堆积程序跑几个小时内存曲线一路上涨最后 OOM。这不是 Kylin 特有但 Linux 环境下没有 Windows 那套资源回收兜底表现更明显。我的习惯是所有 Graphics 和 Bitmap 一律用 using 包裹或 try/finally 里明确调 Dispose绝不用完不管。程序上生产后观察内存曲线是否平稳基本能判断有没有这个毛病。验证、配置、好习惯都到位之后Kylin 上的 libgdiplus 才算真正配完希望帮到你。本文还有配套的精品资源点击获取