已安装unixodbc-dev仍报错：Docker中pecl install sqlsrv提示unixodbc.h缺失

开发者阿泽

2026-8-1

PHP连接MSSQL的Docker构建报错：找不到unixodbc.h（已安装unixodbc-dev）

之前正常运行的Docker构建流程，近期执行pecl install sqlsrv时触发编译错误，提示unixodbc.h: No such file or directory，尽管已经安装了unixodbc-dev。尝试过PHP 7.0-8.1各版本（含FPM/非FPM）、多种msodbcsql及unixodbc/sqlsrv版本，问题仍未解决。

原Dockerfile：

FROM  --platform=linux/amd64 php:8.0-fpm

RUN apt-get update && apt-get -y install nano apt-utils libxml2-dev gnupg \
    && apt-get install -y zlib1g-dev \
    && apt-get install -y libzip-dev \
    && docker-php-ext-install zip 

RUN apt-get -y install libicu-dev gcc g++ make autoconf libc-dev pkg-config libssl-dev apt-transport-https libgss3 

# Install MS ODBC Driver for SQL Server
RUN curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - \
    && curl https://packages.microsoft.com/config/debian/10/prod.list > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update

# Automatically accept the terms from Microsoft
RUN apt-get install -y unixodbc unixodbc-dev odbcinst locales
RUN ACCEPT_EULA=Y apt-get install -y msodbcsql17
RUN apt-get -y install gcc g++ make autoconf libc-dev pkg-config
RUN apt-get update 
RUN pecl install sqlsrv
RUN pecl install pdo_sqlsrv
RUN docker-php-ext-enable sqlsrv pdo_sqlsrv

报错信息：

#0 41.16 In file included from /usr/include/sql.h:19,
#0 41.16                  from /tmp/pear/temp/sqlsrv/shared/xplat.h:30,
#0 41.16                  from /tmp/pear/temp/sqlsrv/shared/typedefs_for_linux.h:23,
#0 41.16                  from /tmp/pear/temp/sqlsrv/shared/xplat_winnls.h:24,
#0 41.16                  from /tmp/pear/temp/sqlsrv/shared/FormattedPrint.h:24,
#0 41.16                  from /tmp/pear/temp/sqlsrv/shared/core_sqlsrv.h:41,
#0 41.16                  from /tmp/pear/temp/sqlsrv/php_sqlsrv_int.h:25,
#0 41.16                  from /tmp/pear/temp/sqlsrv/conn.cpp:24:
#0 41.16 /usr/include/sqltypes.h:56:10: fatal error: unixodbc.h: No such file or directory
#0 41.16    56 | #include "unixodbc.h"
#0 41.16       |          ^~~~~~~~~~~~
#0 41.16 compilation terminated.
#0 41.18 make: *** [Makefile:209: conn.lo] Error 1
#0 41.19 ERROR: `make' failed

解决方案

1. 修改Dockerfile，优化依赖安装顺序与编译配置

核心问题是编译sqlsrv时无法自动定位unixodbc的头文件路径，通过调整安装顺序、指定pkg-config路径可以解决。以下是修复后的Dockerfile：

FROM --platform=linux/amd64 php:8.0-fpm

# 合并基础依赖安装，减少镜像层并确保unixodbc-dev提前安装
RUN apt-get update && apt-get -y install --no-install-recommends \
    nano apt-utils libxml2-dev gnupg zlib1g-dev libzip-dev \
    libicu-dev gcc g++ make autoconf libc-dev pkg-config libssl-dev apt-transport-https libgss3 \
    unixodbc unixodbc-dev odbcinst locales \
    && docker-php-ext-install zip \
    && rm -rf /var/lib/apt/lists/*

# 安装MS ODBC Driver for SQL Server
RUN curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - \
    && curl https://packages.microsoft.com/config/debian/10/prod.list > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update \
    && ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql17 \
    && rm -rf /var/lib/apt/lists/*

# 确保pkg-config能识别unixodbc配置，然后安装并启用扩展
RUN echo "/usr/lib/x86_64-linux-gnu/pkgconfig" >> /etc/pkgconfig.conf \
    && pkg-config --list-all | grep odbc \
    && pecl install sqlsrv pdo_sqlsrv \
    && docker-php-ext-enable sqlsrv pdo_sqlsrv

2. 关键修改说明

合并所有依赖安装步骤，避免重复执行apt-get update，同时保证unixodbc-dev在msodbcsql17之前安装
添加--no-install-recommends参数减少冗余包，缩小镜像体积
手动将unixodbc的pkgconfig目录加入系统配置，确保编译工具能找到头文件路径
合并pecl install命令，减少不必要的镜像层

3. 排查验证步骤（如果问题仍存在）

进入构建失败的临时容器，检查头文件是否存在：

docker run --rm -it <失败镜像的ID> bash
find /usr -name unixodbc.h

检查pkg-config是否能识别unixodbc：
```
pkg-config --cflags unixodbc
```
正常输出应包含-I/usr/include之类的路径，若没有则手动设置环境变量：
```
export PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH
```

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