Nginx 配置检查报 server_names_hash_bucket_size: 64

添加较长的域名后，nginx -t 失败，日志要求增加哈希桶大小：

nginx: [emerg] could not build server_names_hash, you should increase server_names_hash_bucket_size: 64
nginx: configuration file /etc/nginx/nginx.conf test failed

把配置写成 server_names_hash_bucket_size 64;，错误仍然不变。这里冒号后的 64 表示发生错误时使用的值，并不是要求你设置到 64。已经是 64 时，再显式写一次 64 不会增加容量。

本文针对这条只要求增加 server_names_hash_bucket_size 的致命错误。它在 Ubuntu 的 Nginx 1.14.0 中存在，当前 Nginx 的配置规则和错误含义也一致；不要把它理解为某个版本特有的缺陷。其他包含 optimal、either 或 max_size 的提示，需要按完整日志区分。

先确认检查的是哪份配置

在与部署一致的测试环境中，先看版本及编译参数，核对运行实例实际使用的配置入口：

nginx -V
nginx -t -c /etc/nginx/nginx.conf

以上路径是假定值，需要替换为该实例的真实主配置。启动时用了 -p 等参数，检查时也应保持一致；容器内的配置要用对应镜像及挂载内容判断，不能拿宿主机另一份 Nginx 的结果代替。

查看主配置和它引入的文件，找到已有的 server_names_hash_bucket_size 与最近增加的 server_name。这能区分“当前桶确实不够大”和“编辑了未加载的文件”。如果域名来自模板，核对生成后的内容，避免把错误拼接出的长字符串当成正常域名继续调参。

Nginx 1.9.2 及以上可用下面的命令辅助查看配置：

nginx -T -c /etc/nginx/nginx.conf

-T 同时执行配置检查，失败时不要指望它输出完整配置，仍需沿主文件中的 include 查找。输出可能含内部地址或其他敏感设置，应留在受控环境中。-t 还会尝试打开配置引用的文件，因此权限、证书或日志路径问题也可能让检查失败。

在已有 http 块里把 64 调到 128

这条错误说明当前桶无法容纳需要存储的名称条目。名称内容之外还有结构开销，不能只比较域名字数和数字 64，也不宜把某个固定域名长度当作所有平台的门槛。默认桶大小与处理器缓存行有关，不一定都是 32 或 64。

确认域名本身正确后，对开头的 : 64 场景，可先把桶大小提高到下一个 2 的幂，即 128。修改前备份实际配置及生成模板，备份放到不会被 include 匹配的位置。

在现有的 http 块中修改或添加下面这一行：

server_names_hash_bucket_size 128;

不要另建一个嵌套的 http 块，也不要放进 server 或 location。下面仅展示位置关系，不是可用于覆盖主配置的完整文件：

http {
    server_names_hash_bucket_size 128;

    # 保留原有的其他 http 设置和站点 include
}

如果同一层级已经有该指令，修改原来的一项，避免重复声明。通过 http 内的 include 引入的片段可以直接写这条指令，但目录名字本身不能保证上下文，仍要查看 include 所在位置。

128 是针对当前 64 的下一步调整，不是所有站点的统一值。修改后重新检查；如果错误明确变成 : 128，先确认当前加载的名称没有异常，再考虑下一个值。不要一次设成很大的数字来掩盖配置问题，哈希布局和内存使用也会随之改变。

日志同时提到 max_size 时，处理顺序不同

如果完整日志要求增加 server_names_hash_max_size 或 server_names_hash_bucket_size 中的任意一个，尤其是大量域名场景，应先考虑哈希表的最大大小。可先让 server_names_hash_max_size 接近配置的服务器名称数量，再检查结果；只有仍无法满足要求或配置处理时间不可接受时，再考虑增加桶大小。

这与单个名称条目放不进桶的错误不同。只增加哈希表容量，不能让一个桶装下更大的条目。

还要分清 [warn] could not build optimal server_names_hash 与开头的 [emerg] could not build server_names_hash。警告不等于这次配置检查一定失败，应继续看完整输出及退出状态；不能只看到 hash 就认定服务无法启动，也不能因此忽略后面的其他错误。

检查通过后再重载，并保留回退路径

改好后，用原来的程序和入口再次检查：

nginx -t -c /etc/nginx/nginx.conf

确认检查成功且没有未处理的配置错误，再通过该实例既有的服务管理方式加载。直接管理 master 进程、并确认下列入口对应运行实例时，重载命令为：

nginx -s reload -c /etc/nginx/nginx.conf

服务管理器、面板或容器统一控制的环境，应沿用它的加载方式和启动参数。已经退出的服务不能靠 reload 启动，应在配置检查通过后按原部署流程启动。

重载后查看错误日志，确认新配置被接受，并访问新增域名及已有站点，检查是否返回预期内容。Nginx 应用新配置失败时可以继续运行旧配置，因此网站仍能打开并不能证明这次修改成功；同样，-T 显示磁盘内容，也不代表运行中的 worker 已采用它。

如果调整引入回归，恢复已知可用的配置和模板，再检查并加载。若新增域名正是触发条件，只把桶大小降回 64、却保留新增域名，可能重新触发同一错误；需要一并撤回该次域名变更，或保留已经验证可容纳它的桶大小。