Heroku部署ASP.NET Core报libgdiplus缺失、Gdip初始化异常如何解决

核心问题根因 #

报错Unable to load shared library 'libgdiplus'的本质是应用运行的Heroku dyno环境内缺少GDI+对应的系统依赖，本地运行正常是因为本地Windows/macOS环境自带GDI+系统库，和代码逻辑无关。绝大多数场景下问题来自两个点：Docker多阶段构建时把依赖装在了编译阶段而非最终运行阶段、libgdiplus安装后未做软链接导致.NET运行时找不到库文件。

分步修复方案 #

• 修正Dockerfile的依赖安装位置
  标准ASP.NET Core Dockerfile为多阶段构建结构，如果你把apt-get install libgdiplus写在SDK编译阶段，最终生成的运行时镜像不会包含该依赖。必须将依赖安装逻辑放在ASP.NET Core运行时基础镜像的层中，参考正确配置：

  # 最终运行阶段（runtime层）
  FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
  WORKDIR /app
  # 安装系统依赖，加--no-install-recommends减小镜像体积，安装后清理apt缓存
  RUN apt-get update \
      && apt-get install -y --no-install-recommends libgdiplus libc6-dev \
      && apt-get clean \
      && rm -rf /var/lib/apt/lists/*
  # 补全软链接，解决.NET默认库查找路径和apt安装路径不一致的问题
  RUN ln -sf /usr/lib/x86_64-linux-gnu/libgdiplus.so /usr/lib/libgdiplus.so
  
  # 以下为常规编译发布逻辑，保持原有配置即可
  FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
  WORKDIR /src
  COPY ["YourApiProject/YourApiProject.csproj", "YourApiProject/"]
  RUN dotnet restore "YourApiProject/YourApiProject.csproj"
  COPY . .
  WORKDIR "/src/YourApiProject"
  RUN dotnet build "YourApiProject.csproj" -c Release -o /app/build
  
  FROM build AS publish
  RUN dotnet publish "YourApiProject.csproj" -c Release -o /app/publish /p:UseAppHost=false
  
  FROM base AS final
  WORKDIR /app
  COPY --from=publish /app/publish .
  ENTRYPOINT ["dotnet", "YourApiProject.dll"]
  

• 如果你未使用Dockerfile部署，而是直接通过Heroku .NET buildpack部署
  Heroku默认.NET buildpack不会自动安装libgdiplus，需要先给应用添加apt构建包支持，再在项目根目录新建名为Aptfile的文件，文件内写入以下内容提交后重新部署即可：

  libgdiplus
  libc6-dev
  

• 部署后验证依赖是否生效
  重新部署完成后，执行heroku run bash进入运行中的dyno命令行，运行ldconfig -p | grep libgdiplus，如果输出包含libgdiplus.so的路径信息，说明依赖已经正确安装，重启应用即可恢复正常。
• 无依赖替代方案（推荐毕设场景快速落地）
  微软官方已明确标注System.Drawing.Common仅在Windows环境下受支持，Linux/macOS场景不推荐生产使用。你可以直接将图像处理逻辑替换为SixLabors.ImageSharp，这是完全托管实现的图像处理库，不需要安装任何系统依赖，替换Image.FromStream的代码改动量极小，部署后不会再出现类似系统库缺失的问题。

注意：不要通过heroku run bash进入dyno手动执行apt安装依赖，Heroku dyno为无状态运行环境，实例重启后所有手动修改的内容都会被清空，所有依赖安装逻辑必须写入构建流程。

内容的提问来源于stack exchange，提问作者Hieu Le