建與collectstatic靜態(tài)文件收集)
最近幫兩個(gè)團(tuán)隊(duì)做上線前的最后檢查發(fā)現(xiàn)大家無(wú)一例外卡在同一組問(wèn)題上收集靜態(tài)文件、構(gòu)建前端、安裝依賴。不管是剛做完的 Django 電商項(xiàng)目還是帶 Vue 前端的后臺(tái)管理系統(tǒng)只要不是純返回 JSON 的接口項(xiàng)目基本都會(huì)撞上這堵墻。今天這篇不繞彎子把這套流程拆開(kāi)講透每步都給你能直接抄作業(yè)的命令和配置。我見(jiàn)過(guò)太多本地跑得好好的一上線就白屏的案例。Django 開(kāi)發(fā)模式下靜態(tài)文件是自動(dòng)帶服務(wù)的根本不需要你操心可一旦切到生產(chǎn)環(huán)境樣式、圖片、JS 一夜之間全失蹤admin 后臺(tái)跟毛坯房似的。這篇文章適合兩類人剛寫完 Django 項(xiàng)目準(zhǔn)備部署的新手以及已經(jīng)把流程跑通但一直沒(méi)搞懂原理、總被各種異常炸得措手不及的開(kāi)發(fā)者?？赐昴憔湍塥?dú)立把裝依賴 → 構(gòu)建前端 → 收集靜態(tài)文件這條鏈完整走下來(lái)。1. 項(xiàng)目現(xiàn)場(chǎng)為什么這三件事總是一起暴雷1.1 Django 靜態(tài)資源的兩副面孔Django 的靜態(tài)文件默認(rèn)有兩副完全不同的面孔。開(kāi)發(fā)模式下你只需要在DEBUGTrue狀態(tài)運(yùn)行runserverDjango 會(huì)自動(dòng)把每個(gè) app 的static/目錄、你在STATICFILES_DIRS里寫的所有額外目錄通通映射到/static/這個(gè) URL 前綴下。這段時(shí)期你幾乎感覺(jué)不到靜態(tài)文件的存在改完 CSS 刷新就能看見(jiàn)體驗(yàn)非常好。一旦進(jìn)入生產(chǎn)環(huán)境DEBUGFalseDjango 立刻撒手不管靜態(tài)服務(wù)。這個(gè)設(shè)計(jì)的根本原因是性能開(kāi)發(fā)服務(wù)器是單進(jìn)程的簡(jiǎn)易服務(wù)扛不住真實(shí)用戶的并發(fā)請(qǐng)求也絕對(duì)不該出現(xiàn)在生產(chǎn)環(huán)境。此時(shí)所有靜態(tài)文件必須被統(tǒng)一收集到一個(gè)獨(dú)立的真實(shí)目錄再交給 Nginx、CDN 或 WhiteNoise 這類高性能代理去服務(wù)。好多人沒(méi)意識(shí)到這副面孔的存在結(jié)果就是把代碼傳到服務(wù)器后頁(yè)面主體是出來(lái)了可 CSS 全部 404。1.2 現(xiàn)代 Django 項(xiàng)目的三明治結(jié)構(gòu)現(xiàn)在的 Django 項(xiàng)目很少是純服務(wù)端渲染了。最常見(jiàn)的是兩類形態(tài)一種是 Django 只做 API 后端前端是獨(dú)立的 Vue/React 工程另一種是 Django 負(fù)責(zé)頁(yè)面渲染同時(shí)引用了前端打包工具產(chǎn)出的靜態(tài)資源還有一類是純 Django 項(xiàng)目但會(huì)用到 Django admin 自帶的靜態(tài)資源。這三種形態(tài)最終都會(huì)指向同一個(gè)宿命你得把分散在app/static/目錄、前端構(gòu)建目錄、第三方依賴庫(kù)里的所有靜態(tài)文件全部匯合到一處。我經(jīng)常拿三明治形容這種結(jié)構(gòu)——Django 是底層面包靜態(tài)文件是中間那層肉餅前端構(gòu)建和 admin 插件是上層的蔬菜不把它們壓緊成一整個(gè)三明治端上桌就是一盤散沙。1.3 三個(gè)環(huán)節(jié)是一條流水線說(shuō)到這你已經(jīng)看出來(lái)了安裝依賴、構(gòu)建前端、收集靜態(tài)文件不是三個(gè)獨(dú)立動(dòng)作而是同一條流水線上的三道工序。Python 依賴裝不全Django 服務(wù)起不來(lái)Node 依賴沒(méi)裝好前端產(chǎn)物構(gòu)建不了前端產(chǎn)物構(gòu)建完成還不算完不執(zhí)行collectstatic的話這些產(chǎn)物根本不會(huì)出現(xiàn)在生產(chǎn)環(huán)境該有的位置。我見(jiàn)過(guò)最典型的情況是開(kāi)發(fā)者在本地直接DEBUGTrue開(kāi)跑壓根沒(méi)強(qiáng)制自己走完這條鏈于是遺漏問(wèn)題被積壓到最后。等到上線前才第一次執(zhí)行collectstatic各種缺文件、路徑不對(duì)、admin 樣式全丟的問(wèn)題一股腦涌出來(lái)根本沒(méi)時(shí)間一個(gè)個(gè)排查。提前把這條流水線打熟真的比什么都重要。2. 安裝依賴Python 側(cè)和 Node 側(cè)都要鎖版本2.1 Python 依賴從 requirements.txt 到虛擬環(huán)境Python 側(cè)的第一件事是選對(duì)依賴管理方式。小項(xiàng)目用最樸素的requirements.txt就夠但關(guān)鍵是格式要嚴(yán)謹(jǐn)。下面這種寫法是我推薦的基礎(chǔ)版本django5.2.0 djangorestframework3.16.0 celery5.3,5.4 gunicorn23.0.0我特別強(qiáng)調(diào)精確鎖版而不是。你可能會(huì)想用不是更省心嗎裝新版本還能收獲安全修復(fù)。但在實(shí)際部署里會(huì)讓同一份代碼在不同時(shí)間的安裝結(jié)果變得不可預(yù)測(cè)。上個(gè)月跑得好好的代碼這個(gè)月因?yàn)槟硞€(gè)依賴發(fā)布了新版可能直接掛掉。經(jīng)典事故是 Django 補(bǔ)丁版本升級(jí)后某個(gè)第三方庫(kù)的兼容性崩了而你根本不知道發(fā)生了什么。團(tuán)隊(duì)協(xié)作時(shí)更是如此——同事裝了新版本你這邊還是舊的線上環(huán)境再給你來(lái)個(gè)驚喜版本誰(shuí)也說(shuō)不清線上跑的是哪套了。裝依賴前一定要建虛擬環(huán)境。這步被無(wú)數(shù)新手跳過(guò)后果就是把自己機(jī)器上的 Python 全局環(huán)境攪成一鍋粥。Django 版本沖突、site-packages目錄臃腫、卸載都不敢卸。用下面這套命令python -m venv venv source venv/bin/activate # Linux/macOS venv\Scripts\activate # Windows pip install -r requirements.txt如果你在國(guó)內(nèi)網(wǎng)絡(luò)環(huán)境下直接pip install可能會(huì)慢到讓你懷疑人生。我會(huì)把 pip 配置指到國(guó)內(nèi)鏡像源在~/.pip/pip.confWindows 在%APPDATA%\pip\pip.ini里寫入[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn裝完之后別忘了做兩件事pip list --outdated看看有哪些依賴有新版以及pip check檢查依賴間是否有沖突。這兩條命令在服務(wù)器部署后尤其值得跑一次能幫你跳過(guò)很多隱蔽的雷。2.2 Node 依賴npm 工具的選型與加速如果前端是獨(dú)立工程Python 依賴處理完緊接著就要裝 Node 依賴。這里首先要搞清楚dependencies和devDependencies的區(qū)別真正打進(jìn)前端產(chǎn)物的庫(kù)比如vue、react、組件庫(kù)放在dependencies而vite、webpack、eslint這些只在開(kāi)發(fā)/構(gòu)建期使用的工具放在devDependencies。如果你采用在代碼倉(cāng)庫(kù)里提交構(gòu)建產(chǎn)物的部署策略那部署服務(wù)器上甚至不需要裝devDependencies但更常見(jiàn)的做法是服務(wù)器上拿到源碼后現(xiàn)場(chǎng)構(gòu)建這時(shí)候就要求全部依賴都裝齊。安裝命令的選擇我現(xiàn)在的建議就一條小項(xiàng)目用 npm 默認(rèn)即可中大型項(xiàng)目?jī)?yōu)先 pnpm。pnpm 對(duì)磁盤占用、安裝速度的把控甩開(kāi) npm 一大截。但不管用哪個(gè)我都強(qiáng)烈建議把 lock 文件提交到 Git 倉(cāng)庫(kù)。npm 對(duì)應(yīng)package-lock.jsonpnpm 對(duì)應(yīng)pnpm-lock.yaml。鎖定文件的意義和 Python 的requirements.txt鎖版本完全一致保證所有人、所有環(huán)境裝出來(lái)的依賴樹(shù)完全一致。部署時(shí)如果要在服務(wù)器上執(zhí)行安裝推薦用這條npm ci --registryhttps://registry.npmmirror.comnpm ci和npm install的區(qū)別在于它會(huì)嚴(yán)格按 lock 文件安裝絕無(wú)順便升級(jí)一個(gè)小版本的騷操作而且會(huì)先清空node_modules干凈利落。你要是直接用npm install在極端情況下真的會(huì)改掉 lock 文件這可不是什么好事情。2.3 依賴版本的鎖定哲學(xué)依賴鎖版本這件事說(shuō)到底是一個(gè)工程紀(jì)律問(wèn)題。我見(jiàn)過(guò)太多項(xiàng)目代碼是新的requirements.txt卻是三年前的或者package.json里寫的^18.2.0build 的時(shí)候?qū)嶋H裝出來(lái)的 React 已經(jīng)十八點(diǎn)幾版本了。上線前一切正常上線后突然報(bào)錯(cuò)查到最后就是依賴漂移。我的實(shí)操建議是工程的根目錄維護(hù)一個(gè)setup.sh把兩套依賴的安裝和版本檢查都寫進(jìn)去這樣團(tuán)隊(duì)任何成員拿到項(xiàng)目一條命令就能把 Python 和 Node 的依賴都就位。下面是一個(gè)精簡(jiǎn)版腳本我在多個(gè)項(xiàng)目里復(fù)用效果不錯(cuò)#!/bin/bash set -e python -m venv venv source venv/bin/activate pip install -r requirements.txt pip check cd frontend npm ci --registryhttps://registry.npmmirror.com右鍵可執(zhí)行、丟進(jìn) CI、或者扔給新同事都行。依賴管理做到這一步才算真正讓人省心。3. 構(gòu)建前端從源代碼到靜態(tài)產(chǎn)物3.1 為什么要先構(gòu)建再交給 Django很多人搞不明白為什么前端源碼不能直接丟給 Django非要多一步構(gòu)建?，F(xiàn)在前端源碼幾乎都是 Vue 單文件組件、TypeScript、JSX、SCSS 這類瀏覽器不可能直接識(shí)別的東西。瀏覽器只認(rèn) ES5/ES6 時(shí)代的原生 JS 和標(biāo)準(zhǔn) CSS。構(gòu)建工具Vite、Webpack要干的事就是轉(zhuǎn)譯、壓縮、合并、打指紋。打指紋這一點(diǎn)值得展開(kāi)講講。構(gòu)建后的文件名經(jīng)常長(zhǎng)這樣index-3c9e1f2b.js。每次構(gòu)建內(nèi)容變化后面的哈希串就變。這個(gè)設(shè)計(jì)對(duì)緩存策略極其友好——文件內(nèi)容沒(méi)變文件名不變?yōu)g覽器可以放心地永久緩存一旦代碼更新文件名變化瀏覽器自然會(huì)去拿新文件。Django 里如果你使用ManifestStaticFilesStorage還會(huì)生成一個(gè)staticfiles.json映射表專門用來(lái)管理這種帶哈希的文件名避免直接在模板里寫死。整個(gè)構(gòu)建鏈路里最關(guān)鍵的問(wèn)題不是構(gòu)建多久而是構(gòu)建出來(lái)之后產(chǎn)物流放到哪、訪問(wèn)前綴是什么。3.2 關(guān)鍵配置publicPath 與 STATIC_URL 之間的對(duì)暗號(hào)這是整個(gè)前端Django 協(xié)作里最大的坑沒(méi)有之一。構(gòu)建工具打包出來(lái)的 HTML 里會(huì)引用 CSS/JS 文件的路徑而這個(gè)路徑前綴由構(gòu)建工具的publicPath或base配置決定。如果這個(gè)前綴和 Django 的STATIC_URL對(duì)不上就會(huì)出現(xiàn)文件明明存在但瀏覽器請(qǐng)求 404的詭異現(xiàn)象。Vite 項(xiàng)目的vite.config.js里base配置import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ base: /static/web/, plugins: [vue()] })對(duì)應(yīng)的 Djangosettings.pySTATIC_URL /static/ STATICFILES_DIRS [ BASE_DIR / frontend/dist, ]這樣構(gòu)建出來(lái)的 HTML 里引用的地址就會(huì)是/static/web/assets/index-xxx.jsDjango 在接收到這個(gè)請(qǐng)求后會(huì)去STATICFILES_DIRS指向的frontend/dist里找匹配文件。這個(gè)對(duì)暗號(hào)的過(guò)程我愿稱之為整個(gè)集成流程中最容易翻車的環(huán)節(jié)結(jié)果還偏偏很少有人提前講清楚。如果用的是 Webpack對(duì)應(yīng)配置項(xiàng)是output.publicPathoutput: { publicPath: /static/web/ }它們?cè)谠砩贤耆恢隆Ｄ阌?Angular、Svelte、還是純手寫編譯只要是構(gòu)建后產(chǎn)物帶一個(gè) URL 前綴的機(jī)制就得遵循同樣的匹配邏輯。怎么檢查有沒(méi)有對(duì)好構(gòu)建完成后直接打開(kāi)dist/index.html看引用的路徑前綴再用瀏覽器訪問(wèn)一下這個(gè)路徑。就這么簡(jiǎn)單粗暴。3.3 構(gòu)建產(chǎn)物輸出策略dist 目錄怎么接給 Django 項(xiàng)目用的前端構(gòu)建產(chǎn)物最常用的接收方式有兩種。第一種前端工程獨(dú)立放在frontend/目錄構(gòu)建產(chǎn)物輸出到frontend/dist/然后 Django 在STATICFILES_DIRS里加上這一項(xiàng)。這種方式結(jié)構(gòu)清晰前端后端互不干擾適合前后端代碼同一個(gè)倉(cāng)庫(kù)但目錄隔離的中型項(xiàng)目。第二種直接把構(gòu)建目錄設(shè)為 Django 的某個(gè)已有靜態(tài)目錄比如project/static/web/。對(duì)純 Django 小項(xiàng)目更友好省得再配置一層路徑。但要注意這會(huì)讓構(gòu)建工具每次 build 都往同一個(gè)目錄寫文件舊文件殘留問(wèn)題明顯必須做好清理策略。不管哪種方式核心原則是前端產(chǎn)物是靜態(tài)文件源之一不能只放在一個(gè) Django 找不到的地方。如果你構(gòu)建產(chǎn)物輸出到了frontend/dist卻忘了在STATICFILES_DIRS里加路徑那collectstatic后服務(wù)器上自然什么都沒(méi)有。我個(gè)人的偏好是第一類方案——獨(dú)立frontend/目錄加dist輸出然后STATICFILES_DIRS引用它。這樣如果將來(lái)前端要拆出去獨(dú)立部署Django 這邊只需刪掉一個(gè)配置項(xiàng)改動(dòng)成本幾乎為零。4. 收集靜態(tài)文件collectstatic 前后到底發(fā)生了什么4.1 三個(gè) STATIC 配置項(xiàng)的定位很多朋友會(huì)把STATIC_URL、STATIC_ROOT、STATICFILES_DIRS這幾個(gè)配置搞混其實(shí)它們的定位非常清晰配置項(xiàng)作用示例STATIC_URL用戶訪問(wèn)靜態(tài)資源時(shí)的 URL 前綴/static/STATIC_ROOT收集后文件存放的絕對(duì)路徑部署服務(wù)器真實(shí)服務(wù)目錄/var/www/example/staticfiles/STATICFILES_DIRS額外靜態(tài)文件源目錄列表collect 時(shí)的供貨倉(cāng)庫(kù)[BASE_DIR / frontend/dist]STATIC_ROOT是目的STATICFILES_DIRS是源頭。這個(gè)關(guān)系如果搞反你會(huì)在配置里看到錯(cuò)誤地把STATIC_ROOT寫進(jìn)STATICFILES_DIRS的操作Django 直接報(bào)警或生成循環(huán)。打個(gè)比方STATICFILES_DIRS是你家里的幾個(gè)儲(chǔ)物柜STATIC_ROOT是搬家公司的貨車車廂collectstatic就是把所有柜子里的東西全部清空裝進(jìn)貨車——所以絕不能讓貨車車廂同時(shí)也是儲(chǔ)物柜之一那會(huì)裝出個(gè)悖論來(lái)。4.2 collectstatic 的完整行為邏輯collectstatic的核心邏輯其實(shí)不復(fù)雜Django 啟動(dòng)時(shí)會(huì)用一組 finder 去各個(gè)靜態(tài)文件源里翻找文件然后復(fù)制到STATIC_ROOT。默認(rèn)有兩個(gè) finderFileSystemFinder掃描STATICFILES_DIRS里配置的所有絕對(duì)路徑。AppDirectoriesFinder掃描每個(gè) Django app 下的static/子目錄。當(dāng)兩個(gè) finder 都提供了同名文件時(shí)FileSystemFinder的優(yōu)先級(jí)更高也就是STATICFILES_DIRS里的文件會(huì)覆蓋 app 內(nèi)置的。實(shí)際執(zhí)行時(shí)我更推薦每次都帶--noinput和--clear參數(shù)python manage.py collectstatic --noinput --clear--noinput是不再詢問(wèn)是否覆蓋同名文件適合部署腳本中執(zhí)行--clear會(huì)先清空STATIC_ROOT再重新收集。這兩個(gè)參數(shù)的意義在哪兒如果你不加--clear舊版本構(gòu)建的文件不容易被清掉在哈希文件名的場(chǎng)景下還能忍但在沒(méi)有哈希、同名覆蓋的場(chǎng)景就會(huì)殘留陳舊文件用戶刷新時(shí)先拿到舊的過(guò)會(huì)緩存失效才拿到新的說(shuō)不清道不明的怪問(wèn)題就這么來(lái)的。想只做模擬演練不實(shí)際改動(dòng)任何文件時(shí)用--dry-run預(yù)覽一下輸出能讓你提前知道 collect 后到底有哪些文件python manage.py collectstatic --dry-run4.3 生產(chǎn)環(huán)境中最常見(jiàn)的收集姿勢(shì)生產(chǎn)環(huán)境里collectstatic的執(zhí)行時(shí)機(jī)通常發(fā)生在兩類節(jié)點(diǎn)。一類是裸機(jī)或云服務(wù)器部署走一個(gè) shell 腳本另一類是 Docker 鏡像構(gòu)建階段。裸機(jī)部署的部署順序我強(qiáng)烈建議按這樣來(lái)cd /path/to/project git pull source venv/bin/activate pip install -r requirements.txt cd frontend npm ci npm run build cd .. python manage.py migrate python manage.py collectstatic --noinput --clear python manage.py checkDjango 官方不建議遷移和collectstatic隨便亂跑但它們確實(shí)有強(qiáng)順序依賴先把數(shù)據(jù)庫(kù)結(jié)構(gòu)就位再把靜態(tài)資源就位最后啟動(dòng)服務(wù)。很多人的誤區(qū)是上來(lái)先重啟 Nginx/Gunicorn再說(shuō)收集靜態(tài)文件——順序反了用戶訪問(wèn)的前幾秒就會(huì)拿到一個(gè)殘缺的站點(diǎn)。如果走 Docker 路線我通常在 Dockerfile 里把 collect 放在構(gòu)建階段這樣最終鏡像本身就已經(jīng)包含全部靜態(tài)文件運(yùn)行時(shí)容器不需要依賴外部目錄。一個(gè)典型的多階段 Dockerfile 片段FROM node:20-slim AS frontend WORKDIR /app/frontend COPY frontend/package.json ./ RUN npm ci COPY frontend/ . RUN npm run build FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY --fromfrontend /app/frontend/dist /app/frontend/dist COPY . . ENV DEBUGFalse RUN python manage.py collectstatic --noinput --clear CMD [gunicorn, your_project.wsgi:application, --bind, 0.0.0.0:8000]這種做法的好處是鏡像構(gòu)建失敗時(shí)能盡早暴露問(wèn)題而collectstatic一旦在構(gòu)建階段成功運(yùn)行時(shí)基本不再依賴任何構(gòu)建產(chǎn)物。代價(jià)是鏡像體積會(huì)大一點(diǎn)但收益遠(yuǎn)大于成本。5. 一條龍實(shí)操五步完成依賴 → 構(gòu)建 → 收集的完整閉環(huán)5.1 準(zhǔn)備一個(gè)可復(fù)現(xiàn)的 Demo 結(jié)構(gòu)理論說(shuō)了這么多我們來(lái)看一個(gè)能直接跑通的完整例子。目錄結(jié)構(gòu)是這樣example_project/ ├── manage.py ├── requirements.txt ├── config/ │ ├── settings.py │ ├── urls.py │ └── wsgi.py ├── myapp/ │ └── static/ │ └── myapp/ │ └── css/ │ └── app.css └── frontend/ ├── package.json ├── vite.config.js ├── index.html └── src/ └── main.js前端是 Vite Vue 的最小工程Django 這邊只有一個(gè)自定義 app外加 admin 的靜態(tài)資源。部署目標(biāo)就是前端構(gòu)建產(chǎn)物和 Django app 自帶靜態(tài)文件、admin 靜態(tài)文件全部匯集到STATIC_ROOT由 Nginx 統(tǒng)一服務(wù)。5.2 五步操作清單第一步創(chuàng)建虛擬環(huán)境并安裝 Python 依賴務(wù)必帶上--check校驗(yàn)依賴樹(shù)完整性python -m venv venv source venv/bin/activate pip install -r requirements.txt pip check第二步安裝前端依賴并構(gòu)建產(chǎn)物。全程使用npm ci來(lái)還原 lock 文件的一致性然后執(zhí)行生產(chǎn)構(gòu)建cd frontend npm ci npm run build第三步確認(rèn)settings.py里靜態(tài)文件相關(guān)配置正確。下面是一個(gè)入門級(jí)但非常穩(wěn)妥的配置STATIC_URL /static/ STATICFILES_DIRS [ BASE_DIR / frontend/dist, ] STATIC_ROOT BASE_DIR.parent / staticfiles注意我把STATIC_ROOT放在項(xiàng)目外層的staticfiles/目錄這樣避免它成為 Django 可掃描的代碼文件。生產(chǎn)里你也可以改成/var/www/staticfiles之類的絕對(duì)路徑。第四步執(zhí)行收集命令并用findstatic驗(yàn)證python manage.py collectstatic --noinput --clear python manage.py findstatic myapp/css/app.css python manage.py findstatic admin/css/base.cssfindstatic是排查靜態(tài)文件問(wèn)題的好幫手它會(huì)直接告訴你某個(gè)文件是否找到、在哪找到。admin 的樣式就是通過(guò)這條命令驗(yàn)證的因?yàn)闆](méi)人想在收集完才發(fā)現(xiàn) admin 后臺(tái)裸奔。第五步配置 Nginx 指向STATIC_ROOT。一個(gè)精簡(jiǎn)的 Nginx 配置片段server { listen 80; server_name example.com; location /static/ { alias /path/to/staticfiles/; expires 30d; } location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }關(guān)鍵點(diǎn)是alias后面那個(gè)路徑必須和STATIC_ROOT完全一致如果 slug 用root指令而不是alias路徑拼接方式完全不同很容易踩坑。對(duì)于帶哈希文件名的產(chǎn)物expires 30d這種長(zhǎng)緩存是安全的但對(duì)沒(méi)哈希的文件緩存時(shí)間別設(shè)那么長(zhǎng)否則改代碼后用戶還死死抱著舊文件。5.3 驗(yàn)證清單上線前值得跑一遍的檢查我每次上線前都會(huì)強(qiáng)制自己過(guò)一遍這一串檢查建議你也保存下來(lái)ls $STATIC_ROOT/myapp/css/確認(rèn)文件真實(shí)存在。瀏覽器打開(kāi)/static/myapp/css/app.css確認(rèn) HTTP 狀態(tài)是 200 而不是 404。打開(kāi)前端頁(yè)面按 F12看 Network 面板中 CSS/JS 的請(qǐng)求 URL 是否吻合構(gòu)建產(chǎn)物中的引用路徑。訪問(wèn) Django admin 頁(yè)面確認(rèn)后臺(tái)樣式加載正常。python manage.py check --deploy讓 Django 替你做一遍生產(chǎn)環(huán)境安全配置的三方審查靜態(tài)文件相關(guān)告警能提前暴露不少隱患。這套驗(yàn)證做完我基本可以放心地切換到生產(chǎn)模式。你可能會(huì)覺(jué)得麻煩但上線后如果讓用戶先碰見(jiàn)問(wèn)題那才是真麻煩。6. 常見(jiàn)問(wèn)題速查表與避坑心得6.1 我踩過(guò)的典型故障明細(xì)表我把自己這幾年處理過(guò)的、與這三件事相關(guān)的典型故障整理成了速查表你可以直接對(duì)照參考癥狀可能原因排查與解決頁(yè)面 HTML 有的CSS/JS 全 404前端 base/publicPath 與STATIC_URL不一致打開(kāi)dist/index.html檢查引用路徑確認(rèn)base和STATIC_URL匹配CSS/JS 能訪問(wèn)admin 后臺(tái)樣式全丟collectstatic前未收集 admin 靜態(tài)文件或 Nginx 未將/static/指向STATIC_ROOT跑python manage.py findstatic admin/css/base.css驗(yàn)證來(lái)源collectstatic后文件還是舊的前端沒(méi)有重新構(gòu)建或沒(méi)帶--clear先npm run build再collectstatic --clear --noinput找不到/static/web/assets/index-xxx.jsfrontend/dist未加入STATICFILES_DIRS或路徑拼寫錯(cuò)誤檢查STATICFILES_DIRS配置用findstatic web/assets/index-xxx.js驗(yàn)證collectstatic 因權(quán)限失敗Docker 或系統(tǒng)用戶對(duì)STATIC_ROOT無(wú)寫權(quán)限使用RUN mkdir -p和RUN chown給運(yùn)行用戶分配權(quán)限或先手動(dòng)建目錄生產(chǎn)環(huán)境頁(yè)面樣式狂轉(zhuǎn)后端 API 正常ManifestStaticFilesStorage開(kāi)啟后manifest.json缺失先完整跑一遍collectstatic確認(rèn)staticfiles.json生成或暫時(shí)改回默認(rèn) storage依賴安裝報(bào)錯(cuò)報(bào)某個(gè)包無(wú)法編譯環(huán)境缺少編譯工具鏈node-gyp等按官方文檔安裝 Python 和 VS Build Tools 對(duì)應(yīng)版本或嘗試使用預(yù)編譯二進(jìn)制版本這七類問(wèn)題加起來(lái)基本覆蓋了我這些年看到的大部分部署事故。你會(huì)發(fā)現(xiàn)它們的根子全都指向一件事靜態(tài)文件在哪個(gè)環(huán)節(jié)斷了整個(gè)鏈路就斷了。6.2 三個(gè)被反復(fù)翻出來(lái)的避坑心得第一個(gè)心得我反復(fù)強(qiáng)調(diào)都不嫌多把開(kāi)發(fā)模式不等于生產(chǎn)模式刻進(jìn)腦子。每次在本地用DEBUGFalse跑服務(wù)之前先強(qiáng)制自己執(zhí)行一遍collectstatic這是成本最低的提前演練。等到線上崩了再回頭查代價(jià)完全不是一個(gè)數(shù)量級(jí)。第二個(gè)心得前端引用路徑一定要在項(xiàng)目初期就約定好。最省事的約定就是前端產(chǎn)物所有靜態(tài)資源一律掛在/static/下構(gòu)建工具的base或publicPath永遠(yuǎn)搭配STATIC_URL使用。這個(gè)約定一旦定下來(lái)后續(xù)所有運(yùn)營(yíng)、更換域名、接 CDN 都會(huì)輕松很多。越晚改越痛我就是從這種痛里爬出來(lái)的。第三個(gè)心得部署流程必須腳本化。我個(gè)人的做法是項(xiàng)目里放一個(gè)deploy.sh把git pull、依賴安裝、前端構(gòu)建、遷移、收集靜態(tài)文件全部串起來(lái)團(tuán)隊(duì)任何人都可以一鍵執(zhí)行。沒(méi)有腳本化的部署靠記性、靠手打、靠人肉檢查遲早會(huì)出岔子。真實(shí)環(huán)境里出岔子的那天往往就是老板在旁邊盯著的那天。最后分享點(diǎn)個(gè)人的操作體會(huì)這三個(gè)動(dòng)作我原本也是拆開(kāi)做的后來(lái)發(fā)現(xiàn)只要把它們當(dāng)成一套標(biāo)準(zhǔn)流水線、寫進(jìn)部署腳本、配合版本鎖定整個(gè)上線過(guò)程完全可以做到無(wú)腦且可重復(fù)。再給我一次機(jī)會(huì)我會(huì)在項(xiàng)目第一天就把這套流程搭起來(lái)而不是等上線前才慌忙補(bǔ)救。這個(gè)習(xí)慣真的能幫你省下無(wú)數(shù)個(gè)加班之夜。 Django部署全流程拆解：依賴安裝、前端構(gòu)建與collectstatic靜態(tài)文件收集
最近幫兩個(gè)團(tuán)隊(duì)做上線前的最后檢查發(fā)現(xiàn)大家無(wú)一例外卡在同一組問(wèn)題上收集靜態(tài)文件、構(gòu)建前端、安裝依賴。不管是剛做完的 Django 電商項(xiàng)目還是帶 Vue 前端的后臺(tái)管理系統(tǒng)只要不是純返回 JSON 的接口項(xiàng)目基本都會(huì)撞上這堵墻。今天這篇不繞彎子把這套流程拆開(kāi)講透每步都給你能直接抄作業(yè)的命令和配置。我見(jiàn)過(guò)太多本地跑得好好的一上線就白屏的案例。Django 開(kāi)發(fā)模式下靜態(tài)文件是自動(dòng)帶服務(wù)的根本不需要你操心可一旦切到生產(chǎn)環(huán)境樣式、圖片、JS 一夜之間全失蹤admin 后臺(tái)跟毛坯房似的。這篇文章適合兩類人剛寫完 Django 項(xiàng)目準(zhǔn)備部署的新手以及已經(jīng)把流程跑通但一直沒(méi)搞懂原理、總被各種異常炸得措手不及的開(kāi)發(fā)者?？赐昴憔湍塥?dú)立把裝依賴 → 構(gòu)建前端 → 收集靜態(tài)文件這條鏈完整走下來(lái)。1. 項(xiàng)目現(xiàn)場(chǎng)為什么這三件事總是一起暴雷1.1 Django 靜態(tài)資源的兩副面孔Django 的靜態(tài)文件默認(rèn)有兩副完全不同的面孔。開(kāi)發(fā)模式下你只需要在DEBUGTrue狀態(tài)運(yùn)行runserverDjango 會(huì)自動(dòng)把每個(gè) app 的static/目錄、你在STATICFILES_DIRS里寫的所有額外目錄通通映射到/static/這個(gè) URL 前綴下。這段時(shí)期你幾乎感覺(jué)不到靜態(tài)文件的存在改完 CSS 刷新就能看見(jiàn)體驗(yàn)非常好。一旦進(jìn)入生產(chǎn)環(huán)境DEBUGFalseDjango 立刻撒手不管靜態(tài)服務(wù)。這個(gè)設(shè)計(jì)的根本原因是性能開(kāi)發(fā)服務(wù)器是單進(jìn)程的簡(jiǎn)易服務(wù)扛不住真實(shí)用戶的并發(fā)請(qǐng)求也絕對(duì)不該出現(xiàn)在生產(chǎn)環(huán)境。此時(shí)所有靜態(tài)文件必須被統(tǒng)一收集到一個(gè)獨(dú)立的真實(shí)目錄再交給 Nginx、CDN 或 WhiteNoise 這類高性能代理去服務(wù)。好多人沒(méi)意識(shí)到這副面孔的存在結(jié)果就是把代碼傳到服務(wù)器后頁(yè)面主體是出來(lái)了可 CSS 全部 404。1.2 現(xiàn)代 Django 項(xiàng)目的三明治結(jié)構(gòu)現(xiàn)在的 Django 項(xiàng)目很少是純服務(wù)端渲染了。最常見(jiàn)的是兩類形態(tài)一種是 Django 只做 API 后端前端是獨(dú)立的 Vue/React 工程另一種是 Django 負(fù)責(zé)頁(yè)面渲染同時(shí)引用了前端打包工具產(chǎn)出的靜態(tài)資源還有一類是純 Django 項(xiàng)目但會(huì)用到 Django admin 自帶的靜態(tài)資源。這三種形態(tài)最終都會(huì)指向同一個(gè)宿命你得把分散在app/static/目錄、前端構(gòu)建目錄、第三方依賴庫(kù)里的所有靜態(tài)文件全部匯合到一處。我經(jīng)常拿三明治形容這種結(jié)構(gòu)——Django 是底層面包靜態(tài)文件是中間那層肉餅前端構(gòu)建和 admin 插件是上層的蔬菜不把它們壓緊成一整個(gè)三明治端上桌就是一盤散沙。1.3 三個(gè)環(huán)節(jié)是一條流水線說(shuō)到這你已經(jīng)看出來(lái)了安裝依賴、構(gòu)建前端、收集靜態(tài)文件不是三個(gè)獨(dú)立動(dòng)作而是同一條流水線上的三道工序。Python 依賴裝不全Django 服務(wù)起不來(lái)Node 依賴沒(méi)裝好前端產(chǎn)物構(gòu)建不了前端產(chǎn)物構(gòu)建完成還不算完不執(zhí)行collectstatic的話這些產(chǎn)物根本不會(huì)出現(xiàn)在生產(chǎn)環(huán)境該有的位置。我見(jiàn)過(guò)最典型的情況是開(kāi)發(fā)者在本地直接DEBUGTrue開(kāi)跑壓根沒(méi)強(qiáng)制自己走完這條鏈于是遺漏問(wèn)題被積壓到最后。等到上線前才第一次執(zhí)行collectstatic各種缺文件、路徑不對(duì)、admin 樣式全丟的問(wèn)題一股腦涌出來(lái)根本沒(méi)時(shí)間一個(gè)個(gè)排查。提前把這條流水線打熟真的比什么都重要。2. 安裝依賴Python 側(cè)和 Node 側(cè)都要鎖版本2.1 Python 依賴從 requirements.txt 到虛擬環(huán)境Python 側(cè)的第一件事是選對(duì)依賴管理方式。小項(xiàng)目用最樸素的requirements.txt就夠但關(guān)鍵是格式要嚴(yán)謹(jǐn)。下面這種寫法是我推薦的基礎(chǔ)版本django5.2.0 djangorestframework3.16.0 celery5.3,5.4 gunicorn23.0.0我特別強(qiáng)調(diào)精確鎖版而不是。你可能會(huì)想用不是更省心嗎裝新版本還能收獲安全修復(fù)。但在實(shí)際部署里會(huì)讓同一份代碼在不同時(shí)間的安裝結(jié)果變得不可預(yù)測(cè)。上個(gè)月跑得好好的代碼這個(gè)月因?yàn)槟硞€(gè)依賴發(fā)布了新版可能直接掛掉。經(jīng)典事故是 Django 補(bǔ)丁版本升級(jí)后某個(gè)第三方庫(kù)的兼容性崩了而你根本不知道發(fā)生了什么。團(tuán)隊(duì)協(xié)作時(shí)更是如此——同事裝了新版本你這邊還是舊的線上環(huán)境再給你來(lái)個(gè)驚喜版本誰(shuí)也說(shuō)不清線上跑的是哪套了。裝依賴前一定要建虛擬環(huán)境。這步被無(wú)數(shù)新手跳過(guò)后果就是把自己機(jī)器上的 Python 全局環(huán)境攪成一鍋粥。Django 版本沖突、site-packages目錄臃腫、卸載都不敢卸。用下面這套命令python -m venv venv source venv/bin/activate # Linux/macOS venv\Scripts\activate # Windows pip install -r requirements.txt如果你在國(guó)內(nèi)網(wǎng)絡(luò)環(huán)境下直接pip install可能會(huì)慢到讓你懷疑人生。我會(huì)把 pip 配置指到國(guó)內(nèi)鏡像源在~/.pip/pip.confWindows 在%APPDATA%\pip\pip.ini里寫入[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn裝完之后別忘了做兩件事pip list --outdated看看有哪些依賴有新版以及pip check檢查依賴間是否有沖突。這兩條命令在服務(wù)器部署后尤其值得跑一次能幫你跳過(guò)很多隱蔽的雷。2.2 Node 依賴npm 工具的選型與加速如果前端是獨(dú)立工程Python 依賴處理完緊接著就要裝 Node 依賴。這里首先要搞清楚dependencies和devDependencies的區(qū)別真正打進(jìn)前端產(chǎn)物的庫(kù)比如vue、react、組件庫(kù)放在dependencies而vite、webpack、eslint這些只在開(kāi)發(fā)/構(gòu)建期使用的工具放在devDependencies。如果你采用在代碼倉(cāng)庫(kù)里提交構(gòu)建產(chǎn)物的部署策略那部署服務(wù)器上甚至不需要裝devDependencies但更常見(jiàn)的做法是服務(wù)器上拿到源碼后現(xiàn)場(chǎng)構(gòu)建這時(shí)候就要求全部依賴都裝齊。安裝命令的選擇我現(xiàn)在的建議就一條小項(xiàng)目用 npm 默認(rèn)即可中大型項(xiàng)目?jī)?yōu)先 pnpm。pnpm 對(duì)磁盤占用、安裝速度的把控甩開(kāi) npm 一大截。但不管用哪個(gè)我都強(qiáng)烈建議把 lock 文件提交到 Git 倉(cāng)庫(kù)。npm 對(duì)應(yīng)package-lock.jsonpnpm 對(duì)應(yīng)pnpm-lock.yaml。鎖定文件的意義和 Python 的requirements.txt鎖版本完全一致保證所有人、所有環(huán)境裝出來(lái)的依賴樹(shù)完全一致。部署時(shí)如果要在服務(wù)器上執(zhí)行安裝推薦用這條npm ci --registryhttps://registry.npmmirror.comnpm ci和npm install的區(qū)別在于它會(huì)嚴(yán)格按 lock 文件安裝絕無(wú)順便升級(jí)一個(gè)小版本的騷操作而且會(huì)先清空node_modules干凈利落。你要是直接用npm install在極端情況下真的會(huì)改掉 lock 文件這可不是什么好事情。2.3 依賴版本的鎖定哲學(xué)依賴鎖版本這件事說(shuō)到底是一個(gè)工程紀(jì)律問(wèn)題。我見(jiàn)過(guò)太多項(xiàng)目代碼是新的requirements.txt卻是三年前的或者package.json里寫的^18.2.0build 的時(shí)候?qū)嶋H裝出來(lái)的 React 已經(jīng)十八點(diǎn)幾版本了。上線前一切正常上線后突然報(bào)錯(cuò)查到最后就是依賴漂移。我的實(shí)操建議是工程的根目錄維護(hù)一個(gè)setup.sh把兩套依賴的安裝和版本檢查都寫進(jìn)去這樣團(tuán)隊(duì)任何成員拿到項(xiàng)目一條命令就能把 Python 和 Node 的依賴都就位。下面是一個(gè)精簡(jiǎn)版腳本我在多個(gè)項(xiàng)目里復(fù)用效果不錯(cuò)#!/bin/bash set -e python -m venv venv source venv/bin/activate pip install -r requirements.txt pip check cd frontend npm ci --registryhttps://registry.npmmirror.com右鍵可執(zhí)行、丟進(jìn) CI、或者扔給新同事都行。依賴管理做到這一步才算真正讓人省心。3. 構(gòu)建前端從源代碼到靜態(tài)產(chǎn)物3.1 為什么要先構(gòu)建再交給 Django很多人搞不明白為什么前端源碼不能直接丟給 Django非要多一步構(gòu)建?，F(xiàn)在前端源碼幾乎都是 Vue 單文件組件、TypeScript、JSX、SCSS 這類瀏覽器不可能直接識(shí)別的東西。瀏覽器只認(rèn) ES5/ES6 時(shí)代的原生 JS 和標(biāo)準(zhǔn) CSS。構(gòu)建工具Vite、Webpack要干的事就是轉(zhuǎn)譯、壓縮、合并、打指紋。打指紋這一點(diǎn)值得展開(kāi)講講。構(gòu)建后的文件名經(jīng)常長(zhǎng)這樣index-3c9e1f2b.js。每次構(gòu)建內(nèi)容變化后面的哈希串就變。這個(gè)設(shè)計(jì)對(duì)緩存策略極其友好——文件內(nèi)容沒(méi)變文件名不變?yōu)g覽器可以放心地永久緩存一旦代碼更新文件名變化瀏覽器自然會(huì)去拿新文件。Django 里如果你使用ManifestStaticFilesStorage還會(huì)生成一個(gè)staticfiles.json映射表專門用來(lái)管理這種帶哈希的文件名避免直接在模板里寫死。整個(gè)構(gòu)建鏈路里最關(guān)鍵的問(wèn)題不是構(gòu)建多久而是構(gòu)建出來(lái)之后產(chǎn)物流放到哪、訪問(wèn)前綴是什么。3.2 關(guān)鍵配置publicPath 與 STATIC_URL 之間的對(duì)暗號(hào)這是整個(gè)前端Django 協(xié)作里最大的坑沒(méi)有之一。構(gòu)建工具打包出來(lái)的 HTML 里會(huì)引用 CSS/JS 文件的路徑而這個(gè)路徑前綴由構(gòu)建工具的publicPath或base配置決定。如果這個(gè)前綴和 Django 的STATIC_URL對(duì)不上就會(huì)出現(xiàn)文件明明存在但瀏覽器請(qǐng)求 404的詭異現(xiàn)象。Vite 項(xiàng)目的vite.config.js里base配置import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ base: /static/web/, plugins: [vue()] })對(duì)應(yīng)的 Djangosettings.pySTATIC_URL /static/ STATICFILES_DIRS [ BASE_DIR / frontend/dist, ]這樣構(gòu)建出來(lái)的 HTML 里引用的地址就會(huì)是/static/web/assets/index-xxx.jsDjango 在接收到這個(gè)請(qǐng)求后會(huì)去STATICFILES_DIRS指向的frontend/dist里找匹配文件。這個(gè)對(duì)暗號(hào)的過(guò)程我愿稱之為整個(gè)集成流程中最容易翻車的環(huán)節(jié)結(jié)果還偏偏很少有人提前講清楚。如果用的是 Webpack對(duì)應(yīng)配置項(xiàng)是output.publicPathoutput: { publicPath: /static/web/ }它們?cè)谠砩贤耆恢隆Ｄ阌?Angular、Svelte、還是純手寫編譯只要是構(gòu)建后產(chǎn)物帶一個(gè) URL 前綴的機(jī)制就得遵循同樣的匹配邏輯。怎么檢查有沒(méi)有對(duì)好構(gòu)建完成后直接打開(kāi)dist/index.html看引用的路徑前綴再用瀏覽器訪問(wèn)一下這個(gè)路徑。就這么簡(jiǎn)單粗暴。3.3 構(gòu)建產(chǎn)物輸出策略dist 目錄怎么接給 Django 項(xiàng)目用的前端構(gòu)建產(chǎn)物最常用的接收方式有兩種。第一種前端工程獨(dú)立放在frontend/目錄構(gòu)建產(chǎn)物輸出到frontend/dist/然后 Django 在STATICFILES_DIRS里加上這一項(xiàng)。這種方式結(jié)構(gòu)清晰前端后端互不干擾適合前后端代碼同一個(gè)倉(cāng)庫(kù)但目錄隔離的中型項(xiàng)目。第二種直接把構(gòu)建目錄設(shè)為 Django 的某個(gè)已有靜態(tài)目錄比如project/static/web/。對(duì)純 Django 小項(xiàng)目更友好省得再配置一層路徑。但要注意這會(huì)讓構(gòu)建工具每次 build 都往同一個(gè)目錄寫文件舊文件殘留問(wèn)題明顯必須做好清理策略。不管哪種方式核心原則是前端產(chǎn)物是靜態(tài)文件源之一不能只放在一個(gè) Django 找不到的地方。如果你構(gòu)建產(chǎn)物輸出到了frontend/dist卻忘了在STATICFILES_DIRS里加路徑那collectstatic后服務(wù)器上自然什么都沒(méi)有。我個(gè)人的偏好是第一類方案——獨(dú)立frontend/目錄加dist輸出然后STATICFILES_DIRS引用它。這樣如果將來(lái)前端要拆出去獨(dú)立部署Django 這邊只需刪掉一個(gè)配置項(xiàng)改動(dòng)成本幾乎為零。4. 收集靜態(tài)文件collectstatic 前后到底發(fā)生了什么4.1 三個(gè) STATIC 配置項(xiàng)的定位很多朋友會(huì)把STATIC_URL、STATIC_ROOT、STATICFILES_DIRS這幾個(gè)配置搞混其實(shí)它們的定位非常清晰配置項(xiàng)作用示例STATIC_URL用戶訪問(wèn)靜態(tài)資源時(shí)的 URL 前綴/static/STATIC_ROOT收集后文件存放的絕對(duì)路徑部署服務(wù)器真實(shí)服務(wù)目錄/var/www/example/staticfiles/STATICFILES_DIRS額外靜態(tài)文件源目錄列表collect 時(shí)的供貨倉(cāng)庫(kù)[BASE_DIR / frontend/dist]STATIC_ROOT是目的STATICFILES_DIRS是源頭。這個(gè)關(guān)系如果搞反你會(huì)在配置里看到錯(cuò)誤地把STATIC_ROOT寫進(jìn)STATICFILES_DIRS的操作Django 直接報(bào)警或生成循環(huán)。打個(gè)比方STATICFILES_DIRS是你家里的幾個(gè)儲(chǔ)物柜STATIC_ROOT是搬家公司的貨車車廂collectstatic就是把所有柜子里的東西全部清空裝進(jìn)貨車——所以絕不能讓貨車車廂同時(shí)也是儲(chǔ)物柜之一那會(huì)裝出個(gè)悖論來(lái)。4.2 collectstatic 的完整行為邏輯collectstatic的核心邏輯其實(shí)不復(fù)雜Django 啟動(dòng)時(shí)會(huì)用一組 finder 去各個(gè)靜態(tài)文件源里翻找文件然后復(fù)制到STATIC_ROOT。默認(rèn)有兩個(gè) finderFileSystemFinder掃描STATICFILES_DIRS里配置的所有絕對(duì)路徑。AppDirectoriesFinder掃描每個(gè) Django app 下的static/子目錄。當(dāng)兩個(gè) finder 都提供了同名文件時(shí)FileSystemFinder的優(yōu)先級(jí)更高也就是STATICFILES_DIRS里的文件會(huì)覆蓋 app 內(nèi)置的。實(shí)際執(zhí)行時(shí)我更推薦每次都帶--noinput和--clear參數(shù)python manage.py collectstatic --noinput --clear--noinput是不再詢問(wèn)是否覆蓋同名文件適合部署腳本中執(zhí)行--clear會(huì)先清空STATIC_ROOT再重新收集。這兩個(gè)參數(shù)的意義在哪兒如果你不加--clear舊版本構(gòu)建的文件不容易被清掉在哈希文件名的場(chǎng)景下還能忍但在沒(méi)有哈希、同名覆蓋的場(chǎng)景就會(huì)殘留陳舊文件用戶刷新時(shí)先拿到舊的過(guò)會(huì)緩存失效才拿到新的說(shuō)不清道不明的怪問(wèn)題就這么來(lái)的。想只做模擬演練不實(shí)際改動(dòng)任何文件時(shí)用--dry-run預(yù)覽一下輸出能讓你提前知道 collect 后到底有哪些文件python manage.py collectstatic --dry-run4.3 生產(chǎn)環(huán)境中最常見(jiàn)的收集姿勢(shì)生產(chǎn)環(huán)境里collectstatic的執(zhí)行時(shí)機(jī)通常發(fā)生在兩類節(jié)點(diǎn)。一類是裸機(jī)或云服務(wù)器部署走一個(gè) shell 腳本另一類是 Docker 鏡像構(gòu)建階段。裸機(jī)部署的部署順序我強(qiáng)烈建議按這樣來(lái)cd /path/to/project git pull source venv/bin/activate pip install -r requirements.txt cd frontend npm ci npm run build cd .. python manage.py migrate python manage.py collectstatic --noinput --clear python manage.py checkDjango 官方不建議遷移和collectstatic隨便亂跑但它們確實(shí)有強(qiáng)順序依賴先把數(shù)據(jù)庫(kù)結(jié)構(gòu)就位再把靜態(tài)資源就位最后啟動(dòng)服務(wù)。很多人的誤區(qū)是上來(lái)先重啟 Nginx/Gunicorn再說(shuō)收集靜態(tài)文件——順序反了用戶訪問(wèn)的前幾秒就會(huì)拿到一個(gè)殘缺的站點(diǎn)。如果走 Docker 路線我通常在 Dockerfile 里把 collect 放在構(gòu)建階段這樣最終鏡像本身就已經(jīng)包含全部靜態(tài)文件運(yùn)行時(shí)容器不需要依賴外部目錄。一個(gè)典型的多階段 Dockerfile 片段FROM node:20-slim AS frontend WORKDIR /app/frontend COPY frontend/package.json ./ RUN npm ci COPY frontend/ . RUN npm run build FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY --fromfrontend /app/frontend/dist /app/frontend/dist COPY . . ENV DEBUGFalse RUN python manage.py collectstatic --noinput --clear CMD [gunicorn, your_project.wsgi:application, --bind, 0.0.0.0:8000]這種做法的好處是鏡像構(gòu)建失敗時(shí)能盡早暴露問(wèn)題而collectstatic一旦在構(gòu)建階段成功運(yùn)行時(shí)基本不再依賴任何構(gòu)建產(chǎn)物。代價(jià)是鏡像體積會(huì)大一點(diǎn)但收益遠(yuǎn)大于成本。5. 一條龍實(shí)操五步完成依賴 → 構(gòu)建 → 收集的完整閉環(huán)5.1 準(zhǔn)備一個(gè)可復(fù)現(xiàn)的 Demo 結(jié)構(gòu)理論說(shuō)了這么多我們來(lái)看一個(gè)能直接跑通的完整例子。目錄結(jié)構(gòu)是這樣example_project/ ├── manage.py ├── requirements.txt ├── config/ │ ├── settings.py │ ├── urls.py │ └── wsgi.py ├── myapp/ │ └── static/ │ └── myapp/ │ └── css/ │ └── app.css └── frontend/ ├── package.json ├── vite.config.js ├── index.html └── src/ └── main.js前端是 Vite Vue 的最小工程Django 這邊只有一個(gè)自定義 app外加 admin 的靜態(tài)資源。部署目標(biāo)就是前端構(gòu)建產(chǎn)物和 Django app 自帶靜態(tài)文件、admin 靜態(tài)文件全部匯集到STATIC_ROOT由 Nginx 統(tǒng)一服務(wù)。5.2 五步操作清單第一步創(chuàng)建虛擬環(huán)境并安裝 Python 依賴務(wù)必帶上--check校驗(yàn)依賴樹(shù)完整性python -m venv venv source venv/bin/activate pip install -r requirements.txt pip check第二步安裝前端依賴并構(gòu)建產(chǎn)物。全程使用npm ci來(lái)還原 lock 文件的一致性然后執(zhí)行生產(chǎn)構(gòu)建cd frontend npm ci npm run build第三步確認(rèn)settings.py里靜態(tài)文件相關(guān)配置正確。下面是一個(gè)入門級(jí)但非常穩(wěn)妥的配置STATIC_URL /static/ STATICFILES_DIRS [ BASE_DIR / frontend/dist, ] STATIC_ROOT BASE_DIR.parent / staticfiles注意我把STATIC_ROOT放在項(xiàng)目外層的staticfiles/目錄這樣避免它成為 Django 可掃描的代碼文件。生產(chǎn)里你也可以改成/var/www/staticfiles之類的絕對(duì)路徑。第四步執(zhí)行收集命令并用findstatic驗(yàn)證python manage.py collectstatic --noinput --clear python manage.py findstatic myapp/css/app.css python manage.py findstatic admin/css/base.cssfindstatic是排查靜態(tài)文件問(wèn)題的好幫手它會(huì)直接告訴你某個(gè)文件是否找到、在哪找到。admin 的樣式就是通過(guò)這條命令驗(yàn)證的因?yàn)闆](méi)人想在收集完才發(fā)現(xiàn) admin 后臺(tái)裸奔。第五步配置 Nginx 指向STATIC_ROOT。一個(gè)精簡(jiǎn)的 Nginx 配置片段server { listen 80; server_name example.com; location /static/ { alias /path/to/staticfiles/; expires 30d; } location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }關(guān)鍵點(diǎn)是alias后面那個(gè)路徑必須和STATIC_ROOT完全一致如果 slug 用root指令而不是alias路徑拼接方式完全不同很容易踩坑。對(duì)于帶哈希文件名的產(chǎn)物expires 30d這種長(zhǎng)緩存是安全的但對(duì)沒(méi)哈希的文件緩存時(shí)間別設(shè)那么長(zhǎng)否則改代碼后用戶還死死抱著舊文件。5.3 驗(yàn)證清單上線前值得跑一遍的檢查我每次上線前都會(huì)強(qiáng)制自己過(guò)一遍這一串檢查建議你也保存下來(lái)ls $STATIC_ROOT/myapp/css/確認(rèn)文件真實(shí)存在。瀏覽器打開(kāi)/static/myapp/css/app.css確認(rèn) HTTP 狀態(tài)是 200 而不是 404。打開(kāi)前端頁(yè)面按 F12看 Network 面板中 CSS/JS 的請(qǐng)求 URL 是否吻合構(gòu)建產(chǎn)物中的引用路徑。訪問(wèn) Django admin 頁(yè)面確認(rèn)后臺(tái)樣式加載正常。python manage.py check --deploy讓 Django 替你做一遍生產(chǎn)環(huán)境安全配置的三方審查靜態(tài)文件相關(guān)告警能提前暴露不少隱患。這套驗(yàn)證做完我基本可以放心地切換到生產(chǎn)模式。你可能會(huì)覺(jué)得麻煩但上線后如果讓用戶先碰見(jiàn)問(wèn)題那才是真麻煩。6. 常見(jiàn)問(wèn)題速查表與避坑心得6.1 我踩過(guò)的典型故障明細(xì)表我把自己這幾年處理過(guò)的、與這三件事相關(guān)的典型故障整理成了速查表你可以直接對(duì)照參考癥狀可能原因排查與解決頁(yè)面 HTML 有的CSS/JS 全 404前端 base/publicPath 與STATIC_URL不一致打開(kāi)dist/index.html檢查引用路徑確認(rèn)base和STATIC_URL匹配CSS/JS 能訪問(wèn)admin 后臺(tái)樣式全丟collectstatic前未收集 admin 靜態(tài)文件或 Nginx 未將/static/指向STATIC_ROOT跑python manage.py findstatic admin/css/base.css驗(yàn)證來(lái)源collectstatic后文件還是舊的前端沒(méi)有重新構(gòu)建或沒(méi)帶--clear先npm run build再collectstatic --clear --noinput找不到/static/web/assets/index-xxx.jsfrontend/dist未加入STATICFILES_DIRS或路徑拼寫錯(cuò)誤檢查STATICFILES_DIRS配置用findstatic web/assets/index-xxx.js驗(yàn)證collectstatic 因權(quán)限失敗Docker 或系統(tǒng)用戶對(duì)STATIC_ROOT無(wú)寫權(quán)限使用RUN mkdir -p和RUN chown給運(yùn)行用戶分配權(quán)限或先手動(dòng)建目錄生產(chǎn)環(huán)境頁(yè)面樣式狂轉(zhuǎn)后端 API 正常ManifestStaticFilesStorage開(kāi)啟后manifest.json缺失先完整跑一遍collectstatic確認(rèn)staticfiles.json生成或暫時(shí)改回默認(rèn) storage依賴安裝報(bào)錯(cuò)報(bào)某個(gè)包無(wú)法編譯環(huán)境缺少編譯工具鏈node-gyp等按官方文檔安裝 Python 和 VS Build Tools 對(duì)應(yīng)版本或嘗試使用預(yù)編譯二進(jìn)制版本這七類問(wèn)題加起來(lái)基本覆蓋了我這些年看到的大部分部署事故。你會(huì)發(fā)現(xiàn)它們的根子全都指向一件事靜態(tài)文件在哪個(gè)環(huán)節(jié)斷了整個(gè)鏈路就斷了。6.2 三個(gè)被反復(fù)翻出來(lái)的避坑心得第一個(gè)心得我反復(fù)強(qiáng)調(diào)都不嫌多把開(kāi)發(fā)模式不等于生產(chǎn)模式刻進(jìn)腦子。每次在本地用DEBUGFalse跑服務(wù)之前先強(qiáng)制自己執(zhí)行一遍collectstatic這是成本最低的提前演練。等到線上崩了再回頭查代價(jià)完全不是一個(gè)數(shù)量級(jí)。第二個(gè)心得前端引用路徑一定要在項(xiàng)目初期就約定好。最省事的約定就是前端產(chǎn)物所有靜態(tài)資源一律掛在/static/下構(gòu)建工具的base或publicPath永遠(yuǎn)搭配STATIC_URL使用。這個(gè)約定一旦定下來(lái)后續(xù)所有運(yùn)營(yíng)、更換域名、接 CDN 都會(huì)輕松很多。越晚改越痛我就是從這種痛里爬出來(lái)的。第三個(gè)心得部署流程必須腳本化。我個(gè)人的做法是項(xiàng)目里放一個(gè)deploy.sh把git pull、依賴安裝、前端構(gòu)建、遷移、收集靜態(tài)文件全部串起來(lái)團(tuán)隊(duì)任何人都可以一鍵執(zhí)行。沒(méi)有腳本化的部署靠記性、靠手打、靠人肉檢查遲早會(huì)出岔子。真實(shí)環(huán)境里出岔子的那天往往就是老板在旁邊盯著的那天。最后分享點(diǎn)個(gè)人的操作體會(huì)這三個(gè)動(dòng)作我原本也是拆開(kāi)做的后來(lái)發(fā)現(xiàn)只要把它們當(dāng)成一套標(biāo)準(zhǔn)流水線、寫進(jìn)部署腳本、配合版本鎖定整個(gè)上線過(guò)程完全可以做到無(wú)腦且可重復(fù)。再給我一次機(jī)會(huì)我會(huì)在項(xiàng)目第一天就把這套流程搭起來(lái)而不是等上線前才慌忙補(bǔ)救。這個(gè)習(xí)慣真的能幫你省下無(wú)數(shù)個(gè)加班之夜。