先講個我自己的經歷。幾年前我第一次部署一個基于 Nuxt 的 SSR 項目本以為和部署普通 Node 服務差不多結果本地跑得好好的一到服務器就各種 502、白屏、靜態(tài)資源 404。后來一步步排查才發(fā)現問題出在 Node 版本、構建產物、進程守護和反向代理的整條鏈路上。從那以后我總結出一套 nuxt 項目部署的完整流程照著做基本不會再踩坑。這篇文章就把這套經驗完整寫出來從構建選型、環(huán)境準備、PM2 配置到 Nginx 反向代理再到常見的 502、內存溢出、環(huán)境變量丟失等問題的排查思路全部一次講清。不管你是剛接觸 Nuxt 的新手還是已經部署過幾次但總在細節(jié)上翻車的老手這篇都能幫你省下幾個小時。1. 部署前的整體思路拆解Nuxt 項目到底特殊在哪1.1 為什么不能像普通前端項目一樣直接扔進 Nginx很多朋友部署 Vue 項目習慣了npm run build出來一個dist目錄丟到 Nginx 的html目錄里就完事了。但 Nuxt 項目不行或者說要看你怎么用。Nuxt 默認是 SSR服務端渲染模式也就是說請求到達服務器后Nginx 要把請求轉發(fā)給一個 Node.js 進程由這個進程實時渲染出 HTML 再返回給瀏覽器。所以你的服務器上必須有一個常駐的 Node 進程在跑dist目錄只是構建產物的一部分不是全部。你還需要node_modules里的運行時依賴、.nuxt目錄里的服務端代碼以及一套進程管理機制保證它不掛掉。如果你用的是nuxt generate做純靜態(tài)化部署那確實可以像普通前端項目一樣扔進 Nginx但前提是你的項目里沒有動態(tài)數據、沒有用戶登錄態(tài)、沒有服務端接口代理否則靜態(tài)化之后這些功能會直接失效。1.2 三種部署模式的選型SSR、SPA、靜態(tài)化Nuxt 3 里可以通過配置來決定最終部署形態(tài)我的經驗是先想明白這一點再動手不然部署的時候會非常被動。部署模式配置方式適用場景服務器要求SSR默認開啟無需額外配置需要 SEO、動態(tài)數據、用戶交互復雜的站點必須 Node 環(huán)境 進程守護SPAssr: false后臺管理系統(tǒng)、內部工具不追求首屏 SEO構建后純靜態(tài)資源可扔 CDN靜態(tài)化nuxt generate/prerender內容型站點、博客、文檔站內容基本固定任意靜態(tài)服務器即可我見過不少人把 SSR 項目硬生生改成 SPA 部署只因為服務器上不會配 Node 進程結果 SEO 全廢了。反過來也有把純靜態(tài)博客用 SSR 模式部署的白白占著內存。所以第一步就是確認你的場景到底需要哪種模式。1.3 本篇文章采用的方案清單我下面要講的這套流程默認你用的是 SSR 模式這也是 Nuxt 部署里最典型、最容易出問題的一種。涉及到的核心工具有Node.jsLTS 版本Nuxt 3 要求 Node 18 及以上npm 或 pnpm包管理器二選一PM2Node 進程守護工具負責讓服務常駐并開機自啟Nginx反向代理負責把公網流量轉發(fā)給本地 Node 端口Git代碼傳輸部署時把代碼推到服務器這套方案不需要 Docker因為對于中小型項目來說裸機 PM2 Nginx 是最省事、最容易排查問題的組合。Docker 有它的優(yōu)勢但如果你對容器不熟出了問題反而更難定位。2. 服務器環(huán)境準備與項目構建配置2.1 Node.js 版本怎么選這一條我必須放在最前面說因為版本不對后面全白搭。Nuxt 3 官方要求 Node 18 或更高版本但我實測下來 Node 18 和 Node 20 在內存占用和構建速度上有明顯差異Node 20 的構建更快內存峰值稍微低一點。Node 22 目前也穩(wěn)定了不過社區(qū)里有些依賴還沒完全適配建議還是用 Node 20 LTS 最穩(wěn)妥。如果你服務器上已經裝了舊版 Node比如 16 或者 14直接用node -v檢查一下不符合要求就先升級。升級方式我個人推薦用 nvm 管理curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20 node -v裝好之后把默認版本指過去或者寫到.nvmrc文件里這樣以后項目成員切版本也方便。2.2 本地構建還是服務器構建這個問題很多人糾結我的建議是直接在服務器上構建不要本地構建完再傳上去。為什么因為 Nuxt 的構建產物里有部分內容是和操作系統(tǒng)、Node 版本相關的原生模塊比如某些加密庫、圖片處理庫你在本地 Mac 上構建出來的.nuxt產物傳到 Linux 服務器上很可能跑不起來。就算跑起來了也可能因為 glibc 版本不一致出現奇奇怪怪的段錯誤。正確流程是本地把代碼寫好提交到 Git 倉庫服務器上git clone或者git pull拉最新代碼服務器上安裝依賴服務器上執(zhí)行npm run build服務器上用 PM2 啟動這樣保證構建環(huán)境和運行環(huán)境完全一致省掉大量排查時間。2.3 構建命令和產物結構Nuxt 3 的構建命令是npm run build執(zhí)行完會出現兩個關鍵目錄.nuxtNuxt 內部生成的服務端和客戶端代碼運行時需要.outputNuxt 3 的服務器入口打包產物包含server/index.mjs和public/靜態(tài)資源目錄.output/server/index.mjs就是你要用 node 啟動的文件。PM2 配置里指向它就行。這里有個點要注意如果你在服務器上執(zhí)行npm run build時遇到內存不足多半是 Node 的默認堆內存不夠用后面我會專門講怎么調。2.4 依賴安裝npm 還是 pnpm我個人強烈推薦用 pnpm原因很簡單安裝速度快、磁盤占用小、node_modules 結構清晰。但有兩點要注意用 pnpm 安裝依賴后啟動時如果提示找不到某個包先檢查是不是pnpm版本和項目的package.json里packageManager字段沖突如果你部署的服務器內存特別小比如 1Gnpm install比pnpm install更容易因為并發(fā)過高導致 OOM反而 pnpm 更穩(wěn)安裝命令pnpm install --frozen-lockfile--frozen-lockfile會嚴格按照pnpm-lock.yaml安裝避免因為依賴版本漂移導致本地能跑、線上炸掉的經典問題。3. PM2 進程守護與 Nginx 反向代理配置實戰(zhàn)3.1 PM2 配置文件不要用命令行參數硬啟動很多人部署 Node 服務喜歡pm2 start npm -- run start這種臨時命令對于生產環(huán)境我非常不建議。因為你的項目可能有多個環(huán)境測試、預發(fā)、生產每個環(huán)境的環(huán)境變量、端口、日志路徑都不一樣。把這些寫死在命令行里換環(huán)境的時候就得改命令容易出錯。正確做法是寫一個ecosystem.config.cjs文件放到項目根目錄module.exports { apps: [ { name: nuxt-app, exec_mode: fork, instances: 1, script: ./.output/server/index.mjs, env: { NODE_ENV: production, PORT: 3000, NITRO_PORT: 3000, NUXT_PUBLIC_API_BASE: https://api.example.com, }, max_memory_restart: 500M, log_date_format: YYYY-MM-DD HH:mm:ss, error_file: ./logs/err.log, out_file: ./logs/out.log, merge_logs: true, }, ], }幾個參數我解釋一下exec_mode: forkNuxt 3 的index.mjs本身不是 cluster 模式用 fork 最穩(wěn)instances: 1除非你的服務器是多核且壓力很大否則單實例足夠了實例多了反而互相搶內存max_memory_restart: 500M內存超過 500M 自動重啟這是防止內存泄漏把服務器拖死的保命符NUXT_PUBLIC_API_BASE這是 Nuxt 3 運行時公共環(huán)境變量的寫法后面會細說啟動命令pm2 start ecosystem.config.cjs pm2 save pm2 startuppm2 save是保存當前進程列表pm2 startup會生成一個開機自啟腳本這樣服務器重啟后 PM2 會自動拉起你的應用不用每次手動去pm2 start。3.2 環(huán)境變量在 Nuxt 3 里的正確注入姿勢Nuxt 3 的環(huán)境變量和 Vue 2 時期完全不同這里非常容易踩坑。Nuxt 3 里的環(huán)境變量分兩類運行時環(huán)境變量代碼里通過useRuntimeConfig()讀取的變量名稱以NUXT_為前綴啟動時從進程環(huán)境變量里注入構建時環(huán)境變量打包時就被替換進代碼里的變量比如NUXT_PUBLIC_開頭的配置實戰(zhàn)經驗是凡是后端服務地址、內部密鑰這些不能暴露給瀏覽器的用NUXT_前綴只存在于 PM2 的env配置里凡是要暴露給客戶端瀏覽器使用的配置用NUXT_PUBLIC_前綴因為它會打進客戶端 bundle舉個小例子你的nuxt.config.ts里有runtimeConfig: { apiSecret: process.env.NUXT_API_SECRET, public: { apiBase: process.env.NUXT_PUBLIC_API_BASE || /api, }, }部署的時候PM2 的env里寫NUXT_API_SECRETxxxx NUXT_PUBLIC_API_BASEhttps://api.example.com然后在頁面里const config useRuntimeConfig() console.log(config.apiSecret) // 只在服務端有值 console.log(config.public.apiBase) // 客戶端也能拿到這里有個坑如果你在.env文件里寫環(huán)境變量然后本地npm run build這些變量會被編譯進代碼。但你部署時是在服務器上重新構建的所以服務器上必須有一份對應的.env或者通過 PM2 注入。我個人習慣是生產環(huán)境不用.env文件全部通過 PM2 的env注入這樣git status永遠是干凈的不怕密鑰被誤提交。3.3 Nginx 反向代理配置詳解PM2 把服務跑起來后默認監(jiān)聽3000端口。你不能讓用戶直接訪問 3000 端口原因有兩個裸端口看起來不專業(yè)而且用戶記不住Nginx 做反向代理的同時可以順便把 HTTPS、靜態(tài)資源緩存、Gzip 壓縮這些事一起干了這是我最常用的 Nginx 配置server { listen 80; server_name your-domain.com; # 將 http 請求重定向到 https return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/nginx/ssl/your-domain.com.pem; ssl_certificate_key /etc/nginx/ssl/your-domain.com.key; # 請求體大小限制如果項目里有文件上傳這個值要調大 client_max_body_size 20m; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; } # 靜態(tài)資源直接走 Nginx不經過 Node location /_nuxt/ { alias /var/www/nuxt-app/.output/public/_nuxt/; expires 30d; add_header Cache-Control public, immutable; } }這里有兩個細節(jié)特別說明。第一個是proxy_set_header Upgrade和Connection upgrade這一組配置是給 WebSocket 用的。如果項目里有用到 WebSocket比如聊天室、實時通知少了這兩行Socket 連接會握手失敗。第二個是靜態(tài)資源緩存。Nuxt 構建出來的_nuxt目錄下的文件都帶 hash 后綴文件名變了內容才變所以可以放心設置expires 30d和immutable。這樣一來用戶第二次訪問頁面的時候絕大多數靜態(tài)資源直接命中瀏覽器緩存根本不請求服務器大幅降低 Node 進程壓力。3.4 部署腳本一條命令搞定整個流程每次手動登錄服務器敲那么多命令太累了我建議寫一個簡單的部署腳本放在項目deploy.sh里#!/bin/bash set -e echo 拉取最新代碼... git pull origin main echo 安裝依賴... pnpm install --frozen-lockfile echo 構建項目... npm run build echo 重啟 PM2 進程... pm2 reload ecosystem.config.cjs --update-env echo 部署完成pm2 reload和pm2 restart的區(qū)別在于 reload 是零停機重載它先啟動新進程接管流量再殺掉舊進程。對于 SSR 應用來說reload 能避免用戶請求剛好撞上重啟窗口導致的白屏。--update-env這個參數很重要它會強制 PM2 更新環(huán)境變量否則你改了ecosystem.config.cjs里的env配置不帶上這個參數的話舊的進程里還是老環(huán)境變量。4. 部署過程中的典型問題與排查實錄4.1 502 Bad Gateway最常見也最迷惑上線后一訪問就 502這是 SSR 部署最經典的問題。502 的根源是 Nginx 無法連接到你配置的上游服務也就是 PM2 里管理的 Node 進程。排查路徑我固定走這三步先看 PM2 進程活著沒有pm2 list如果 status 顯示errored或者stopped說明進程掛了再看進程日志pm2 logs nuxt-app --lines 100一般日志里會明確報錯原因如果 PM2 顯示進程活著但還是 502直接在服務器上curl http://127.0.0.1:3000如果 curl 不通說明應用監(jiān)聽失敗如果能通就是 Nginx 配置的上游地址不對我碰到過最隱蔽的一種情況是PM2 進程是活的端口也能通但用戶訪問還是 502。查了半天發(fā)現 Nginx 的proxy_pass寫的是http://localhost:3000而服務器上的localhost解析到了::1IPv6但 Node 只監(jiān)聽了 IPv4 的127.0.0.1。改成proxy_pass http://127.0.0.1:3000;就立刻好了。這個坑非常經典建議大家從一開始就寫127.0.0.1而不是localhost。4.2 構建時內存溢出Javascript heap out of memory無服務器或者 1G 小內存服務器上構建 Nuxt 項目很容易看到這個錯誤FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory這就是 Node 默認堆內存上限不夠用了。默認上限大概是 2G但小服務器物理內存可能只有 1G系統(tǒng)會先崩。解決辦法是構建時顯式調大堆內存我一般這樣寫NODE_OPTIONS--max-old-space-size1024 npm run build如果你的服務器有 2G 內存可以給到 1536 或 2048。這個值不是越大越好因為--max-old-space-size只是堆上限給你進程的物理內存配額就那么大設置超過實際可用物理內存反而會觸發(fā)系統(tǒng) OOM Killer進程被強制殺掉。另外一個關聯問題是如果你的服務器內存確實太小比如 512M老實說不太建議跑 Nuxt SSR構建和運行都會很難受。要么升級配置要么把項目改成靜態(tài)化部署。4.3 環(huán)境變量在構建后失真這個是 Nuxt 3 特有的坑我反復遇到。現象是這樣的本地npm run dev的時候一切正常登錄、接口都能通。到了服務器上頁面能打開但所有接口請求都指向了localhost或者 API 地址不對。原因就是環(huán)境變量沒有正確注入到構建過程。Nuxt 3 的runtimeConfig有一個特性從環(huán)境變量映射到 runtimeConfig 時構建時和運行時的優(yōu)先級不一樣。比如你在nuxt.config.ts里寫了runtimeConfig: { public: { apiBase: process.env.NUXT_PUBLIC_API_BASE || /api } }這里process.env.NUXT_PUBLIC_API_BASE是在構建時讀取的。如果你構建時這個環(huán)境變量不存在構建產物里寫死的就是默認值/api。運行時你再往 PM2 里注入NUXT_PUBLIC_API_BASE已經晚了因為構建產物里的代碼已經把/api當成默認值編譯進去了運行時注入的變量不一定能覆蓋已經內聯的默認值。正確的做法是保證服務器構建時的環(huán)境變量和運行時一致或者在nuxt.config.ts的runtimeConfig里不要寫process.env引用而是只寫占位空字符串讓運行時通過useRuntimeConfig()讀取時動態(tài)填入我個人傾向于第一種方案因為更直觀在構建命令前把環(huán)境變量帶上NUXT_PUBLIC_API_BASEhttps://api.example.com npm run build這樣可以確保構建產物里內聯的就是線上正確的地址。4.4 靜態(tài)資源 404 與緩存策略問題部署后 HTML 能打開但頁面里的 JS、CSS 全部 404最常見的原因有這幾個Nginx 的/_nuxt/路徑 alias 寫錯了.output/public/_nuxt/這個目錄路徑沒對上。我一般先ls /var/www/nuxt-app/.output/public/_nuxt/看看目錄到底長什么樣再去改 Nginx 配置。Nuxt 的 baseURL 配置變了如果你在nuxt.config.ts里設置了app.baseURL: /some-prefix/那所有靜態(tài)資源的路徑都會帶上這個前綴Nginx 的 alias 也要對應改。緩存策略過激導致 HTML 被緩存有的朋友給整個站點設置了expires 30d結果頁面 HTML 也被緩存了用戶那邊不管你怎么發(fā)布新版本永遠看到的還是舊頁面。我前面的配置里只對/_nuxt/目錄做了長期緩存根路徑location /沒有設置expires這樣 HTML 每次都是新鮮的。4.5 端口被占用和權限問題如果 PM2 啟動失敗日志里報EADDRINUSE: address already in use :::3000說明 3000 端口被別的進程占了。排查方式lsof -i :3000 kill -9 PID如果端口是 80 或者 443那大概率是之前的 Nginx 還沒起來或者有別的 Web 服務占著同樣用lsof查。關于權限我多說一句不要為了省事直接用 root 跑 PM2 或 Node 進程。生產環(huán)境更合理的做法是用一個單獨的 deploy 用戶把項目的屬主改為這個用戶然后在 Nginx 的proxy_pass里照常轉發(fā)。這樣萬一應用被攻破攻擊者拿到的是低權限用戶的 shell不是 root。這個習慣越早建立越好。5. 部署后的驗證與運維小技巧5.1 上線后的三項驗證部署完成別急著關終端按下面三步快速驗證第一驗證首頁能正常返回 HTML。用 curl 看首頁響應curl -I https://your-domain.com檢查響應頭里有沒有server: nginx以及 HTTP 狀態(tài)碼是否 200。如果你看到響應頭里帶著x-powered-by: Nuxt就不用太意外這是正常的。第二驗證靜態(tài)資源命中緩存。再 curl 一次靜態(tài)文件看響應頭里有沒有Cache-Control: public, immutable。第三驗證 SSR 是否真的生效。在瀏覽器里打開頁面右鍵查看源代碼確認頁面 HTML 里有沒有實際渲染出的內容。如果源代碼里只有一個app空殼說明你的站雖然部署成功了但實際跑的是 SPA 模式SEO 會受影響。5.2 日志管理PM2 日志切割PM2 默認把所有日志寫到同一個文件里時間長了會非常大影響性能。我習慣加一個pm2-logrotate插件pm2 install pm2-logrotate pm2 set pm2-logrotate:max_size 10M pm2 set pm2-logrotate:retain 7 pm2 set pm2-logrotate:compress true這樣每個日志文件超過 10M 就自動切割保留最近 7 份老日志壓縮存起來。運維久了你會發(fā)現日志輪轉配置得好排查問題會非常舒服。5.3 更新發(fā)布時的優(yōu)雅切換前面部署腳本里用的pm2 reload是零停機的但我補充一個細節(jié)如果你的項目有數據庫遷移這類操作不能把遷移代碼和應用發(fā)布混在一次部署里做。否則新代碼起來的時候老的數據庫結構還沒遷移請求一到就報錯。我的經驗是涉及數據庫變更的發(fā)布先手動執(zhí)行遷移再用pm2 reload重啟應用。這樣應用起來的時候數據庫已經是最新結構不會出現中間狀態(tài)。5.4 多環(huán)境部署的推薦做法一個成熟的項目一般至少有三個環(huán)境開發(fā)、測試、生產。每個環(huán)境的 API 地址、密鑰都不同。我最推薦的做法是給每個環(huán)境寫一份獨立的 PM2 配置比如ecosystem.config.test.cjs和ecosystem.config.prod.cjs然后在部署腳本里按環(huán)境參數加載。這一步做在前面你會省下非常多來回改環(huán)境變量的時間。比如說你要發(fā)測試環(huán)境pm2 start ecosystem.config.test.cjs --env test pm2 save這樣測試環(huán)境自動會讀測試的配置生產環(huán)境讀生產的配置互不干擾。運維的人切換環(huán)境的時候也不會因為忘記改環(huán)境變量導致線上事故。6. 我踩過幾次坑之后的個人體會Nuxt 項目部署這事說復雜不算特別復雜但每一步都有隱藏的細節(jié)。如果非要說哪些地方最容易讓人翻車我的排序是環(huán)境變量注入、Node 版本不匹配、Nginx 的 location 和 alias 配置、PM2 的 env 更新時機。這四個坑我都在生產環(huán)境里真實踩過每個都能讓線上服務在“看似正常”的狀態(tài)里悄悄出問題。所以我最后再重復三個實用習慣服務器上構建不要在本地構建完再傳產物環(huán)境變量全部通過 PM2 注入并保證構建時環(huán)境和運行時環(huán)境一致用ecosystem.config.cjs管理啟動配置不要用命令行裸啟動把這三條刻在腦子里你的 Nuxt 項目部署大概率一次就能跑通。真要是遇到玄學問題先看 PM2 日志再看 Nginx 錯誤日志/var/log/nginx/error.log大多數問題都在日志里寫得明明白白。