nginx:stable-alpine配置more_set_headers后无法启动如何解决

第一步：先拿准确报错，不要盲改 #

先执行命令看Nginx的启动错误日志，所有启动问题的根因都会直接打在日志里：

docker-compose logs nginx

常见的报错就三类，对应解决方法如下：

常见报错1：unknown directive "more_set_headers" #

这个是最高发的问题，原因有两个：

• Alpine源里的nginx-mod-http-headers-more包安装后，不会自动给官方nginx:stable-alpine镜像添加模块加载配置，Nginx启动时根本没加载这个模块，自然识别不了模块提供的指令。
• 部分版本下模块安装后的so文件路径和Nginx默认的模块加载路径不匹配。

修复方法 #

修改你的Dockerfile，安装完模块后手动写入模块加载配置，修正后的Dockerfile如下：

FROM nginx:stable-alpine

RUN apk update && \
    apk upgrade --no-cache && \
    apk add --no-cache nginx-mod-http-headers-more && \
    # 手动写入模块加载配置，指定模块so文件的绝对路径
    echo 'load_module /usr/lib/nginx/modules/ngx_http_headers_more_filter_module.so;' > /etc/nginx/modules-enabled/headers-more.conf

ADD ./nginx/default.conf /etc/nginx/conf.d/default.conf
ADD ./nginx/certs /etc/nginx/certs/self-signed

改完重新构建镜像即可。

常见报错2：模块版本不兼容，提示binary mismatch #

如果日志报so文件版本不匹配、二进制不兼容，是因为你用的官方nginx:stable-alpine镜像内置的Nginx，和Alpine软件源里的Nginx编译参数、版本号存在差异，对应的模块包没法兼容。

修复方法 #

二选一即可：

• 把基础镜像换成Alpine源自带的Nginx镜像，自己写启动命令，保证版本和源里的模块完全对齐。
• 直接在构建镜像时从源码编译对应你当前Nginx版本的headers-more模块，不存在版本兼容问题。

常见报错3：directive "more_set_headers" is not allowed here #

这个是指令放置的作用域不对，more_set_headers只能写在http、server、location、location段的if判断块里，不能写在nginx.conf最外层的全局配置块，挪到对应合法作用域即可。

校验流程 #

每次改完配置或者Dockerfile，先不要直接用docker-compose启动，按以下步骤校验：

• 重新构建Nginx镜像：docker-compose build nginx
• 运行容器执行配置校验：docker run --rm 你构建的nginx镜像名 nginx -t

等返回test is successful的结果，再执行docker-compose up -d启动服务即可。
额外注意：如果你后续给Nginx加了配置目录的卷挂载，不要把/etc/nginx/modules-enabled目录覆盖，否则之前写的模块加载配置会被清空，又会回到识别不了指令的问题。

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