Nginx部署HTTP/3的實現(xiàn)步驟

更新時間：2025年09月10日 09:42:31 作者：Yashar Qian

本文介紹了在Nginx中部署HTTP/3的詳細步驟,文中通過示例代碼介紹的非常詳細,對大家的學習或者工作具有一定的參考學習價值,需要的朋友們下面隨著小編來一起學習學習吧

前提條件

操作系統(tǒng)：本文以 Ubuntu 為例，其他 Linux 發(fā)行版步驟類似。
域名與 SSL 證書：需要一個有效的域名和該域名對應的 SSL 證書（例如，從 Let‘s Encrypt 獲?。?。HTTP/3 強制使用加密。
編譯環(huán)境：需要安裝基本的編譯工具和依賴庫。
防火墻：確保防火墻開放 UDP 443 端口（HTTP/3 基于 UDP），而不僅僅是 TCP 443（HTTPS）。

第一步：安裝必要的依賴庫

首先，更新軟件包列表并安裝編譯 Nginx 所需的開發(fā)工具和庫。

sudo apt update
sudo apt install build-essential mercurial pkg-config \
                 libpcre3-dev zlib1g-dev libssl-dev \
                 git cmake golang

mercurial：Cloudflare 的代碼托管在 Mercurial 上，需要此工具來拉取代碼。
libssl-dev：提供 SSL/TLS 支持（BoringSSL 或 OpenSSL 需要）。
git, cmake, golang：編譯 BoringSSL（QUIC 的加密庫）所必需。

第二步：獲取并構建 BoringSSL

Nginx 的 QUIC 實現(xiàn)推薦使用 Google 的 BoringSSL 而不是 OpenSSL。

# 1. 創(chuàng)建一個工作目錄并進入
mkdir ~/nginx-quic && cd ~/nginx-quic

# 2. 克隆 BoringSSL 倉庫
git clone https://github.com/google/boringssl.git
cd boringssl

# 3. BoringSSL 需要 Go 來編譯
mkdir build
cd build
cmake ..
make -j$(nproc) # 使用所有可用的 CPU 核心進行編譯

# 4. 將編譯好的庫安裝到系統(tǒng)目錄
sudo make install

第三步：獲取 Nginx QUIC 分支代碼

使用 Mercurial 克隆 Cloudflare 的 Nginx QUIC 分支。

# 返回到工作目錄根目錄
cd ~/nginx-quic

# 克隆代碼
hg clone -b quic https://hg.nginx.org/nginx-quic

第四步：編譯 Nginx

現(xiàn)在配置并編譯支持 HTTP/3 的 Nginx。

cd nginx-quic

# 運行配置腳本，指定 BoringSSL 路徑和其他模塊
./auto/configure --with-debug \
                 --with-http_v3_module \          # 啟用 HTTP/3 模塊
                 --with-http_ssl_module \         # 啟用 SSL 模塊
                 --with-cc-opt="-I/usr/local/include" \
                 --with-ld-opt="-L/usr/local/lib" \
                 --with-stream_quic_module        # 啟用 QUIC 流模塊

# 編譯并安裝
make -j$(nproc)
sudo make install

默認安裝路徑是 /usr/local/nginx/。

第五步：配置 Nginx

關鍵的一步是修改 Nginx 的配置文件 (/usr/local/nginx/conf/nginx.conf)，在 server 塊中啟用 HTTP/3。

# 在 http 塊中的 server 配置
server {
    listen       443 ssl;
    listen       443 quic reuseport; # 關鍵：啟用 QUIC 并開啟 reuseport

    # 你的域名
    server_name  your_domain.com;

    # SSL 證書路徑（必須）
    ssl_certificate      /path/to/your/fullchain.pem;
    ssl_certificate_key  /path/to/your/privkey.pem;

    # 啟用 TLS 1.3，它與 HTTP/3 配合得更好
    ssl_protocols        TLSv1.2 TLSv1.3;

    # 告訴瀏覽器此服務器支持 HTTP/3
    add_header Alt-Svc 'h3=":443"; ma=86400'; # 重要：端口必須與監(jiān)聽端口一致

    # 你的網(wǎng)站根目錄和其他配置
    location / {
        root   html;
        index  index.html index.htm;
    }
}

配置說明：

listen 443 quic reuseport;：
- quic：指示 Nginx 在此端口上監(jiān)聽 QUIC（HTTP/3）連接。
- reuseport：為每個工作進程創(chuàng)建一個獨立的套接字，顯著提升 QUIC 性能。
add_header Alt-Svc：
- 這是瀏覽器發(fā)現(xiàn)服務器支持 HTTP/3 的機制。
- 當瀏覽器第一次通過 HTTPS（TCP）訪問時，Nginx 會在響應頭中返回 Alt-Svc，告訴瀏覽器：“這個站點在 UDP 443 端口也支持 HTTP/3（h3），下次你可以嘗試用那個。”
- ma=86400 表示此信息可以緩存 86400 秒（一天）。

第六步：啟動 Nginx 并測試

啟動 Nginx：
```
sudo /usr/local/nginx/sbin/nginx
```
檢查 UDP 443 端口是否監(jiān)聽：
```
sudo ss -lanu | grep 443
```
你應該能看到 Nginx 進程在監(jiān)聽 UDP 443 端口。
使用在線工具測試：
- 訪問 https://http3.check
- 輸入你的域名進行測試。如果配置成功，它會顯示 “HTTP/3 is supported”。
使用瀏覽器開發(fā)者工具檢查：
- 用 Chrome 或 Edge 訪問你的網(wǎng)站。
- 打開 開發(fā)者工具 (F12) -> 網(wǎng)絡 (Network) 選項卡。
- 刷新頁面。
- 點擊域名請求，在 標頭 (Headers) 部分查看 protocol 字段。如果顯示 h3，則表示此次連接是通過 HTTP/3 進行的。
- 你也可以在響應頭中看到 alt-svc 的聲明。

常見問題與故障排除

編譯錯誤：最常見的是依賴問題。確保所有依賴庫都已正確安裝，并且 BoringSSL 的路徑正確。
Nginx 啟動報錯：檢查配置文件語法：sudo /usr/local/nginx/sbin/nginx -t。
檢測不到 HTTP/3：
- 確保防火墻放行了 UDP 443 端口。
- 清除瀏覽器緩存，或者嘗試使用隱身模式。瀏覽器可能需要幾次 TCP 訪問后才會嘗試切換到 QUIC。
- 檢查 alt-svc 頭是否正確發(fā)送?？梢允褂?curl -I https://your_domain.com 查看響應頭。
性能調優(yōu)：QUIC 是一個新的傳輸協(xié)議，可能需要針對你的網(wǎng)絡環(huán)境調整 keepalive_timeout、stream_quic_required_address 等參數(shù)。