Sửa lỗi Nginx 'nginx: [emerg] unknown directive' — Lỗi cú pháp cấu hình

TL;DR

Chạy nginx -t để xác định file và số dòng chính xác. Sửa lỗi chính tả, dấu chấm phẩy bị thiếu, hoặc module không khớp. Sau đó reload với systemctl reload nginx.

sudo nginx -t
# Sửa lỗi được hiển thị
sudo systemctl reload nginx

Lỗi Này Có Nghĩa Là Gì

Trước khi áp dụng bất kỳ thay đổi cấu hình nào, Nginx phân tích cú pháp mọi file mà nó tải. Gặp một directive không nhận ra, nó dừng lại ngay:

nginx: [emerg] unknown directive "ssl_stapling" in /etc/nginx/sites-enabled/mysite.conf:14

[emerg] có nghĩa là Nginx từ chối khởi động hoặc reload. Instance đang chạy của bạn vẫn hoạt động bình thường. Nhưng không có thay đổi cấu hình nào có hiệu lực cho đến khi lỗi được sửa.

Bốn nguyên nhân gây ra lỗi này:

Lỗi chính tả trong tên directive (ví dụ: servr_name thay vì server_name)
Một directive thuộc về module chưa được biên dịch vào bản build Nginx của bạn
Một directive được đặt sai context (ví dụ: log_format bên trong server thay vì http)
Dấu ngoặc nhọn bị thiếu hoặc không khớp làm rối bộ phân tích cú pháp

Bước 1 — Chạy Kiểm Tra Cấu Hình và Đọc Kết Quả

Luôn bắt đầu từ đây. Công cụ kiểm tra tích hợp của Nginx cho bạn biết chính xác file, dòng, và tên directive:

sudo nginx -t

Ví dụ kết quả:

nginx: [emerg] unknown directive "proxy_cache_purge" in /etc/nginx/conf.d/cache.conf:8
nginx: configuration file /etc/nginx/nginx.conf test failed

Mở file đó tại số dòng được chỉ định:

sudo nano /etc/nginx/conf.d/cache.conf

Bước 2 — Sửa Các Nguyên Nhân Phổ Biến

Lỗi chính tả trong tên directive

Kiểm tra chính tả so với tài liệu Nginx chính thức. Các lỗi phổ biến trông như sau:

# Sai
servr_name example.com;
acces_log /var/log/nginx/access.log;

# Đúng
server_name example.com;
access_log /var/log/nginx/access.log;

Directive yêu cầu module chưa được cài đặt

Các directive như proxy_cache_purge, geoip_country, hoặc image_filter không đi kèm với gói Nginx mặc định. Kiểm tra những gì binary của bạn thực sự bao gồm:

nginx -V 2>&1 | grep -- '--with'

Thiếu module? Cài gói phù hợp trên Ubuntu/Debian:

# Cho GeoIP
sudo apt install nginx-module-geoip

# Cho image filter
sudo apt install nginx-module-image-filter

Sau đó tải nó ở đầu file /etc/nginx/nginx.conf:

load_module modules/ngx_http_geoip_module.so;

Với các directive của bên thứ ba như proxy_cache_purge, bạn cần biên dịch Nginx với module ngx_cache_purge, hoặc xem xét lại toàn bộ chiến lược cache invalidation của mình.

Directive đặt sai context

Mỗi directive chỉ hợp lệ bên trong một số block nhất định. log_format, chẳng hạn, chỉ thuộc về http — đặt nó trong server và Nginx sẽ từ chối:

# log_format chỉ thuộc về http
http {
    log_format main '$remote_addr "$request" $status';  # Đúng

    server {
        log_format main '$remote_addr "$request"';  # Sai — sẽ báo lỗi
    }
}

Khi không chắc chắn, hãy kiểm tra dòng "Context" của directive trong tài liệu Nginx trước khi di chuyển nó.

Dấu ngoặc nhọn không khớp làm mất context của bộ phân tích

Một dấu ngoặc đóng bị thiếu khiến mọi directive phía sau trông như đang ở sai block. Các thông báo lỗi trở nên rất khó hiểu. Hãy đếm các dấu ngoặc:

grep -c '{' /etc/nginx/sites-enabled/mysite.conf
grep -c '}' /etc/nginx/sites-enabled/mysite.conf

Số lượng phải khớp nhau. Nếu không, hãy tìm dấu ngoặc bị thiếu thủ công hoặc mở file trong trình soạn thảo hỗ trợ nhận diện cú pháp.

Bước 3 — Xác Nhận Bản Sửa Lỗi

Chỉnh sửa file, sau đó kiểm tra trước khi reload. Đừng bao giờ bỏ qua bước này:

sudo nginx -t

Kết quả hợp lệ trông như sau:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Bây giờ hãy reload. Không phải restart — reload là zero-downtime:

sudo systemctl reload nginx

Xác nhận đang hoạt động:

sudo systemctl status nginx
curl -I http://localhost

Bước 4 — Kiểm Tra Tất Cả Các File Được Include

Nginx kéo cấu hình từ nhiều nơi cùng một lúc. Nếu nginx -t trỏ đến file bạn chưa từng chỉnh sửa, hãy tìm cái gì đang include nó:

grep -r 'include' /etc/nginx/nginx.conf /etc/nginx/conf.d/ /etc/nginx/sites-enabled/

Các file cấu hình sao chép từ Docker container hoặc server khác thường tham chiếu các module hoặc cú pháp từ một bản build Nginx khác. Đây là nguồn phổ biến của các lỗi khó hiểu.

Phòng Ngừa

Ba thói quen giúp loại bỏ hầu hết các lỗi này:

Chạy nginx -t trước mỗi lần reload — tích hợp vào deploy script để tự động hóa
Theo dõi /etc/nginx/ trong git. Một diff một dòng phát hiện lỗi chính tả mà mắt thường có thể bỏ qua
Tạo cấu hình Nginx từ YAML template hoặc Ansible? Hãy chạy YAML qua ToolCraft's YAML ↔ JSON Converter trước — phát hiện vấn đề cấu trúc trước khi chúng render thành cấu hình bị lỗi. Chạy trực tiếp trên trình duyệt, không upload dữ liệu
Trên môi trường staging, hãy kiểm tra với cùng phiên bản Nginx như production. Khả năng sử dụng module khác nhau giữa phiên bản 1.18 và 1.24

Tham Khảo Nhanh — Các Directive và Context Của Chúng

http {
    # cấp http: gzip, log_format, upstream, sendfile
    gzip on;

    server {
        # cấp server: listen, server_name, root, ssl_*
        listen 80;
        server_name example.com;
        root /var/www/html;

        location / {
            # cấp location: try_files, proxy_pass, return, rewrite
            try_files $uri $uri/ =404;
        }
    }
}