建與collectstatic靜態(tài)文件收集)
最近幫兩個(gè)團(tuán)隊(duì)做上線前的最后檢查發(fā)現(xiàn)大家無一例外卡在同一組問題上收集靜態(tài)文件、構(gòu)建前端、安裝依賴。不管是剛做完的 Django 電商項(xiàng)目還是帶 Vue 前端的后臺(tái)管理系統(tǒng)只要不是純返回 JSON 的接口項(xiàng)目基本都會(huì)撞上這堵墻。今天這篇不繞彎子把這套流程拆開講透每步都給你能直接抄作業(yè)的命令和配置。我見過太多本地跑得好好的一上線就白屏的案例。Django 開發(fā)模式下靜態(tài)文件是自動(dòng)帶服務(wù)的根本不需要你操心可一旦切到生產(chǎn)環(huán)境樣式、圖片、JS 一夜之間全失蹤admin 后臺(tái)跟毛坯房似的。這篇文章適合兩類人剛寫完 Django 項(xiàng)目準(zhǔn)備部署的新手以及已經(jīng)把流程跑通但一直沒搞懂原理、總被各種異常炸得措手不及的開發(fā)者?？赐昴憔湍塥?dú)立把裝依賴 → 構(gòu)建前端 → 收集靜態(tài)文件這條鏈完整走下來。1. 項(xiàng)目現(xiàn)場(chǎng)為什么這三件事總是一起暴雷1.1 Django 靜態(tài)資源的兩副面孔Django 的靜態(tài)文件默認(rèn)有兩副完全不同的面孔。開發(fā)模式下你只需要在DEBUGTrue狀態(tài)運(yùn)行runserverDjango 會(huì)自動(dòng)把每個(gè) app 的static/目錄、你在STATICFILES_DIRS里寫的所有額外目錄通通映射到/static/這個(gè) URL 前綴下。這段時(shí)期你幾乎感覺不到靜態(tài)文件的存在改完 CSS 刷新就能看見體驗(yàn)非常好。一旦進(jìn)入生產(chǎn)環(huán)境DEBUGFalseDjango 立刻撒手不管靜態(tài)服務(wù)。這個(gè)設(shè)計(jì)的根本原因是性能開發(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ù)。好多人沒意識(shí)到這副面孔的存在結(jié)果就是把代碼傳到服務(wù)器后頁面主體是出來了可 CSS 全部 404。1.2 現(xiàn)代 Django 項(xiàng)目的三明治結(jié)構(gòu)現(xiàn)在的 Django 項(xiàng)目很少是純服務(wù)端渲染了。最常見的是兩類形態(tài)一種是 Django 只做 API 后端前端是獨(dú)立的 Vue/React 工程另一種是 Django 負(fù)責(zé)頁面渲染同時(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é)是一條流水線說到這你已經(jīng)看出來了安裝依賴、構(gòu)建前端、收集靜態(tài)文件不是三個(gè)獨(dú)立動(dòng)作而是同一條流水線上的三道工序。Python 依賴裝不全Django 服務(wù)起不來Node 依賴沒裝好前端產(chǎn)物構(gòu)建不了前端產(chǎn)物構(gòu)建完成還不算完不執(zhí)行collectstatic的話這些產(chǎn)物根本不會(huì)出現(xiàn)在生產(chǎn)環(huán)境該有的位置。我見過最典型的情況是開發(fā)者在本地直接DEBUGTrue開跑壓根沒強(qiáng)制自己走完這條鏈于是遺漏問題被積壓到最后。等到上線前才第一次執(zhí)行collectstatic各種缺文件、路徑不對(duì)、admin 樣式全丟的問題一股腦涌出來根本沒時(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)境再給你來個(gè)驚喜版本誰也說不清線上跑的是哪套了。裝依賴前一定要建虛擬環(huán)境。這步被無數(shù)新手跳過后果就是把自己機(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ù)器部署后尤其值得跑一次能幫你跳過很多隱蔽的雷。2.2 Node 依賴npm 工具的選型與加速如果前端是獨(dú)立工程Python 依賴處理完緊接著就要裝 Node 依賴。這里首先要搞清楚dependencies和devDependencies的區(qū)別真正打進(jìn)前端產(chǎn)物的庫(kù)比如vue、react、組件庫(kù)放在dependencies而vite、webpack、eslint這些只在開發(fā)/構(gòu)建期使用的工具放在devDependencies。如果你采用在代碼倉(cāng)庫(kù)里提交構(gòu)建產(chǎn)物的部署策略那部署服務(wù)器上甚至不需要裝devDependencies但更常見的做法是服務(wù)器上拿到源碼后現(xiàn)場(chǎng)構(gòu)建這時(shí)候就要求全部依賴都裝齊。安裝命令的選擇我現(xiàn)在的建議就一條小項(xiàng)目用 npm 默認(rèn)即可中大型項(xiàng)目?jī)?yōu)先 pnpm。pnpm 對(duì)磁盤占用、安裝速度的把控甩開 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)境裝出來的依賴樹完全一致。部署時(shí)如果要在服務(wù)器上執(zhí)行安裝推薦用這條npm ci --registryhttps://registry.npmmirror.comnpm ci和npm install的區(qū)別在于它會(huì)嚴(yán)格按 lock 文件安裝絕無順便升級(jí)一個(gè)小版本的騷操作而且會(huì)先清空node_modules干凈利落。你要是直接用npm install在極端情況下真的會(huì)改掉 lock 文件這可不是什么好事情。2.3 依賴版本的鎖定哲學(xué)依賴鎖版本這件事說到底是一個(gè)工程紀(jì)律問題。我見過太多項(xiàng)目代碼是新的requirements.txt卻是三年前的或者package.json里寫的^18.2.0build 的時(shí)候?qū)嶋H裝出來的 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)值得展開講講。構(gòu)建后的文件名經(jīng)常長(zhǎng)這樣index-3c9e1f2b.js。每次構(gòu)建內(nèi)容變化后面的哈希串就變。這個(gè)設(shè)計(jì)對(duì)緩存策略極其友好——文件內(nèi)容沒變文件名不變?yōu)g覽器可以放心地永久緩存一旦代碼更新文件名變化瀏覽器自然會(huì)去拿新文件。Django 里如果你使用ManifestStaticFilesStorage還會(huì)生成一個(gè)staticfiles.json映射表專門用來管理這種帶哈希的文件名避免直接在模板里寫死。整個(gè)構(gòu)建鏈路里最關(guān)鍵的問題不是構(gòu)建多久而是構(gòu)建出來之后產(chǎn)物流放到哪、訪問前綴是什么。3.2 關(guān)鍵配置publicPath 與 STATIC_URL 之間的對(duì)暗號(hào)這是整個(gè)前端Django 協(xié)作里最大的坑沒有之一。構(gòu)建工具打包出來的 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)建出來的 HTML 里引用的地址就會(huì)是/static/web/assets/index-xxx.jsDjango 在接收到這個(gè)請(qǐng)求后會(huì)去STATICFILES_DIRS指向的frontend/dist里找匹配文件。這個(gè)對(duì)暗號(hào)的過程我愿稱之為整個(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ī)制就得遵循同樣的匹配邏輯。怎么檢查有沒有對(duì)好構(gòu)建完成后直接打開dist/index.html看引用的路徑前綴再用瀏覽器訪問一下這個(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è)目錄寫文件舊文件殘留問題明顯必須做好清理策略。不管哪種方式核心原則是前端產(chǎn)物是靜態(tài)文件源之一不能只放在一個(gè) Django 找不到的地方。如果你構(gòu)建產(chǎn)物輸出到了frontend/dist卻忘了在STATICFILES_DIRS里加路徑那collectstatic后服務(wù)器上自然什么都沒有。我個(gè)人的偏好是第一類方案——獨(dú)立frontend/目錄加dist輸出然后STATICFILES_DIRS引用它。這樣如果將來前端要拆出去獨(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用戶訪問靜態(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è)悖論來。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是不再詢問是否覆蓋同名文件適合部署腳本中執(zhí)行--clear會(huì)先清空STATIC_ROOT再重新收集。這兩個(gè)參數(shù)的意義在哪兒如果你不加--clear舊版本構(gòu)建的文件不容易被清掉在哈希文件名的場(chǎng)景下還能忍但在沒有哈希、同名覆蓋的場(chǎng)景就會(huì)殘留陳舊文件用戶刷新時(shí)先拿到舊的過會(huì)緩存失效才拿到新的說不清道不明的怪問題就這么來的。想只做模擬演練不實(shí)際改動(dòng)任何文件時(shí)用--dry-run預(yù)覽一下輸出能讓你提前知道 collect 后到底有哪些文件python manage.py collectstatic --dry-run4.3 生產(chǎn)環(huán)境中最常見的收集姿勢(shì)生產(chǎn)環(huán)境里collectstatic的執(zhí)行時(shí)機(jī)通常發(fā)生在兩類節(jié)點(diǎn)。一類是裸機(jī)或云服務(wù)器部署走一個(gè) shell 腳本另一類是 Docker 鏡像構(gòu)建階段。裸機(jī)部署的部署順序我強(qiáng)烈建議按這樣來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ū)是上來先重啟 Nginx/Gunicorn再說收集靜態(tài)文件——順序反了用戶訪問的前幾秒就會(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í)能盡早暴露問題而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)理論說了這么多我們來看一個(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)依賴樹完整性python -m venv venv source venv/bin/activate pip install -r requirements.txt pip check第二步安裝前端依賴并構(gòu)建產(chǎn)物。全程使用npm ci來還原 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)文件問題的好幫手它會(huì)直接告訴你某個(gè)文件是否找到、在哪找到。admin 的樣式就是通過這條命令驗(yàn)證的因?yàn)闆]人想在收集完才發(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ì)沒哈希的文件緩存時(shí)間別設(shè)那么長(zhǎng)否則改代碼后用戶還死死抱著舊文件。5.3 驗(yàn)證清單上線前值得跑一遍的檢查我每次上線前都會(huì)強(qiáng)制自己過一遍這一串檢查建議你也保存下來ls $STATIC_ROOT/myapp/css/確認(rèn)文件真實(shí)存在。瀏覽器打開/static/myapp/css/app.css確認(rèn) HTTP 狀態(tài)是 200 而不是 404。打開前端頁面按 F12看 Network 面板中 CSS/JS 的請(qǐng)求 URL 是否吻合構(gòu)建產(chǎn)物中的引用路徑。訪問 Django admin 頁面確認(rèn)后臺(tái)樣式加載正常。python manage.py check --deploy讓 Django 替你做一遍生產(chǎn)環(huán)境安全配置的三方審查靜態(tài)文件相關(guān)告警能提前暴露不少隱患。這套驗(yàn)證做完我基本可以放心地切換到生產(chǎn)模式。你可能會(huì)覺得麻煩但上線后如果讓用戶先碰見問題那才是真麻煩。6. 常見問題速查表與避坑心得6.1 我踩過的典型故障明細(xì)表我把自己這幾年處理過的、與這三件事相關(guān)的典型故障整理成了速查表你可以直接對(duì)照參考癥狀可能原因排查與解決頁面 HTML 有的CSS/JS 全 404前端 base/publicPath 與STATIC_URL不一致打開dist/index.html檢查引用路徑確認(rèn)base和STATIC_URL匹配CSS/JS 能訪問admin 后臺(tái)樣式全丟collectstatic前未收集 admin 靜態(tài)文件或 Nginx 未將/static/指向STATIC_ROOT跑python manage.py findstatic admin/css/base.css驗(yàn)證來源collectstatic后文件還是舊的前端沒有重新構(gòu)建或沒帶--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無寫權(quán)限使用RUN mkdir -p和RUN chown給運(yùn)行用戶分配權(quán)限或先手動(dòng)建目錄生產(chǎn)環(huán)境頁面樣式狂轉(zhuǎn)后端 API 正常ManifestStaticFilesStorage開啟后manifest.json缺失先完整跑一遍collectstatic確認(rèn)staticfiles.json生成或暫時(shí)改回默認(rèn) storage依賴安裝報(bào)錯(cuò)報(bào)某個(gè)包無法編譯環(huán)境缺少編譯工具鏈node-gyp等按官方文檔安裝 Python 和 VS Build Tools 對(duì)應(yīng)版本或嘗試使用預(yù)編譯二進(jìn)制版本這七類問題加起來基本覆蓋了我這些年看到的大部分部署事故。你會(huì)發(fā)現(xiàn)它們的根子全都指向一件事靜態(tài)文件在哪個(gè)環(huán)節(jié)斷了整個(gè)鏈路就斷了。6.2 三個(gè)被反復(fù)翻出來的避坑心得第一個(gè)心得我反復(fù)強(qiáng)調(diào)都不嫌多把開發(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è)約定一旦定下來后續(xù)所有運(yùn)營(yíng)、更換域名、接 CDN 都會(huì)輕松很多。越晚改越痛我就是從這種痛里爬出來的。第三個(gè)心得部署流程必須腳本化。我個(gè)人的做法是項(xiàng)目里放一個(gè)deploy.sh把git pull、依賴安裝、前端構(gòu)建、遷移、收集靜態(tài)文件全部串起來團(tuán)隊(duì)任何人都可以一鍵執(zhí)行。沒有腳本化的部署靠記性、靠手打、靠人肉檢查遲早會(huì)出岔子。真實(shí)環(huán)境里出岔子的那天往往就是老板在旁邊盯著的那天。最后分享點(diǎn)個(gè)人的操作體會(huì)這三個(gè)動(dòng)作我原本也是拆開做的后來發(fā)現(xiàn)只要把它們當(dāng)成一套標(biāo)準(zhǔn)流水線、寫進(jìn)部署腳本、配合版本鎖定整個(gè)上線過程完全可以做到無腦且可重復(fù)。再給我一次機(jī)會(huì)我會(huì)在項(xiàng)目第一天就把這套流程搭起來而不是等上線前才慌忙補(bǔ)救。這個(gè)習(xí)慣真的能幫你省下無數(shù)個(gè)加班之夜。 Django部署全流程拆解：依賴安裝、前端構(gòu)建與collectstatic靜態(tài)文件收集
最近幫兩個(gè)團(tuán)隊(duì)做上線前的最后檢查發(fā)現(xiàn)大家無一例外卡在同一組問題上收集靜態(tài)文件、構(gòu)建前端、安裝依賴。不管是剛做完的 Django 電商項(xiàng)目還是帶 Vue 前端的后臺(tái)管理系統(tǒng)只要不是純返回 JSON 的接口項(xiàng)目基本都會(huì)撞上這堵墻。今天這篇不繞彎子把這套流程拆開講透每步都給你能直接抄作業(yè)的命令和配置。我見過太多本地跑得好好的一上線就白屏的案例。Django 開發(fā)模式下靜態(tài)文件是自動(dòng)帶服務(wù)的根本不需要你操心可一旦切到生產(chǎn)環(huán)境樣式、圖片、JS 一夜之間全失蹤admin 后臺(tái)跟毛坯房似的。這篇文章適合兩類人剛寫完 Django 項(xiàng)目準(zhǔn)備部署的新手以及已經(jīng)把流程跑通但一直沒搞懂原理、總被各種異常炸得措手不及的開發(fā)者?？赐昴憔湍塥?dú)立把裝依賴 → 構(gòu)建前端 → 收集靜態(tài)文件這條鏈完整走下來。1. 項(xiàng)目現(xiàn)場(chǎng)為什么這三件事總是一起暴雷1.1 Django 靜態(tài)資源的兩副面孔Django 的靜態(tài)文件默認(rèn)有兩副完全不同的面孔。開發(fā)模式下你只需要在DEBUGTrue狀態(tài)運(yùn)行runserverDjango 會(huì)自動(dòng)把每個(gè) app 的static/目錄、你在STATICFILES_DIRS里寫的所有額外目錄通通映射到/static/這個(gè) URL 前綴下。這段時(shí)期你幾乎感覺不到靜態(tài)文件的存在改完 CSS 刷新就能看見體驗(yàn)非常好。一旦進(jìn)入生產(chǎn)環(huán)境DEBUGFalseDjango 立刻撒手不管靜態(tài)服務(wù)。這個(gè)設(shè)計(jì)的根本原因是性能開發(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ù)。好多人沒意識(shí)到這副面孔的存在結(jié)果就是把代碼傳到服務(wù)器后頁面主體是出來了可 CSS 全部 404。1.2 現(xiàn)代 Django 項(xiàng)目的三明治結(jié)構(gòu)現(xiàn)在的 Django 項(xiàng)目很少是純服務(wù)端渲染了。最常見的是兩類形態(tài)一種是 Django 只做 API 后端前端是獨(dú)立的 Vue/React 工程另一種是 Django 負(fù)責(zé)頁面渲染同時(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é)是一條流水線說到這你已經(jīng)看出來了安裝依賴、構(gòu)建前端、收集靜態(tài)文件不是三個(gè)獨(dú)立動(dòng)作而是同一條流水線上的三道工序。Python 依賴裝不全Django 服務(wù)起不來Node 依賴沒裝好前端產(chǎn)物構(gòu)建不了前端產(chǎn)物構(gòu)建完成還不算完不執(zhí)行collectstatic的話這些產(chǎn)物根本不會(huì)出現(xiàn)在生產(chǎn)環(huán)境該有的位置。我見過最典型的情況是開發(fā)者在本地直接DEBUGTrue開跑壓根沒強(qiáng)制自己走完這條鏈于是遺漏問題被積壓到最后。等到上線前才第一次執(zhí)行collectstatic各種缺文件、路徑不對(duì)、admin 樣式全丟的問題一股腦涌出來根本沒時(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)境再給你來個(gè)驚喜版本誰也說不清線上跑的是哪套了。裝依賴前一定要建虛擬環(huán)境。這步被無數(shù)新手跳過后果就是把自己機(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ù)器部署后尤其值得跑一次能幫你跳過很多隱蔽的雷。2.2 Node 依賴npm 工具的選型與加速如果前端是獨(dú)立工程Python 依賴處理完緊接著就要裝 Node 依賴。這里首先要搞清楚dependencies和devDependencies的區(qū)別真正打進(jìn)前端產(chǎn)物的庫(kù)比如vue、react、組件庫(kù)放在dependencies而vite、webpack、eslint這些只在開發(fā)/構(gòu)建期使用的工具放在devDependencies。如果你采用在代碼倉(cāng)庫(kù)里提交構(gòu)建產(chǎn)物的部署策略那部署服務(wù)器上甚至不需要裝devDependencies但更常見的做法是服務(wù)器上拿到源碼后現(xiàn)場(chǎng)構(gòu)建這時(shí)候就要求全部依賴都裝齊。安裝命令的選擇我現(xiàn)在的建議就一條小項(xiàng)目用 npm 默認(rèn)即可中大型項(xiàng)目?jī)?yōu)先 pnpm。pnpm 對(duì)磁盤占用、安裝速度的把控甩開 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)境裝出來的依賴樹完全一致。部署時(shí)如果要在服務(wù)器上執(zhí)行安裝推薦用這條npm ci --registryhttps://registry.npmmirror.comnpm ci和npm install的區(qū)別在于它會(huì)嚴(yán)格按 lock 文件安裝絕無順便升級(jí)一個(gè)小版本的騷操作而且會(huì)先清空node_modules干凈利落。你要是直接用npm install在極端情況下真的會(huì)改掉 lock 文件這可不是什么好事情。2.3 依賴版本的鎖定哲學(xué)依賴鎖版本這件事說到底是一個(gè)工程紀(jì)律問題。我見過太多項(xiàng)目代碼是新的requirements.txt卻是三年前的或者package.json里寫的^18.2.0build 的時(shí)候?qū)嶋H裝出來的 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)值得展開講講。構(gòu)建后的文件名經(jīng)常長(zhǎng)這樣index-3c9e1f2b.js。每次構(gòu)建內(nèi)容變化后面的哈希串就變。這個(gè)設(shè)計(jì)對(duì)緩存策略極其友好——文件內(nèi)容沒變文件名不變?yōu)g覽器可以放心地永久緩存一旦代碼更新文件名變化瀏覽器自然會(huì)去拿新文件。Django 里如果你使用ManifestStaticFilesStorage還會(huì)生成一個(gè)staticfiles.json映射表專門用來管理這種帶哈希的文件名避免直接在模板里寫死。整個(gè)構(gòu)建鏈路里最關(guān)鍵的問題不是構(gòu)建多久而是構(gòu)建出來之后產(chǎn)物流放到哪、訪問前綴是什么。3.2 關(guān)鍵配置publicPath 與 STATIC_URL 之間的對(duì)暗號(hào)這是整個(gè)前端Django 協(xié)作里最大的坑沒有之一。構(gòu)建工具打包出來的 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)建出來的 HTML 里引用的地址就會(huì)是/static/web/assets/index-xxx.jsDjango 在接收到這個(gè)請(qǐng)求后會(huì)去STATICFILES_DIRS指向的frontend/dist里找匹配文件。這個(gè)對(duì)暗號(hào)的過程我愿稱之為整個(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ī)制就得遵循同樣的匹配邏輯。怎么檢查有沒有對(duì)好構(gòu)建完成后直接打開dist/index.html看引用的路徑前綴再用瀏覽器訪問一下這個(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è)目錄寫文件舊文件殘留問題明顯必須做好清理策略。不管哪種方式核心原則是前端產(chǎn)物是靜態(tài)文件源之一不能只放在一個(gè) Django 找不到的地方。如果你構(gòu)建產(chǎn)物輸出到了frontend/dist卻忘了在STATICFILES_DIRS里加路徑那collectstatic后服務(wù)器上自然什么都沒有。我個(gè)人的偏好是第一類方案——獨(dú)立frontend/目錄加dist輸出然后STATICFILES_DIRS引用它。這樣如果將來前端要拆出去獨(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用戶訪問靜態(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è)悖論來。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是不再詢問是否覆蓋同名文件適合部署腳本中執(zhí)行--clear會(huì)先清空STATIC_ROOT再重新收集。這兩個(gè)參數(shù)的意義在哪兒如果你不加--clear舊版本構(gòu)建的文件不容易被清掉在哈希文件名的場(chǎng)景下還能忍但在沒有哈希、同名覆蓋的場(chǎng)景就會(huì)殘留陳舊文件用戶刷新時(shí)先拿到舊的過會(huì)緩存失效才拿到新的說不清道不明的怪問題就這么來的。想只做模擬演練不實(shí)際改動(dòng)任何文件時(shí)用--dry-run預(yù)覽一下輸出能讓你提前知道 collect 后到底有哪些文件python manage.py collectstatic --dry-run4.3 生產(chǎn)環(huán)境中最常見的收集姿勢(shì)生產(chǎn)環(huán)境里collectstatic的執(zhí)行時(shí)機(jī)通常發(fā)生在兩類節(jié)點(diǎn)。一類是裸機(jī)或云服務(wù)器部署走一個(gè) shell 腳本另一類是 Docker 鏡像構(gòu)建階段。裸機(jī)部署的部署順序我強(qiáng)烈建議按這樣來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ū)是上來先重啟 Nginx/Gunicorn再說收集靜態(tài)文件——順序反了用戶訪問的前幾秒就會(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í)能盡早暴露問題而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)理論說了這么多我們來看一個(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)依賴樹完整性python -m venv venv source venv/bin/activate pip install -r requirements.txt pip check第二步安裝前端依賴并構(gòu)建產(chǎn)物。全程使用npm ci來還原 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)文件問題的好幫手它會(huì)直接告訴你某個(gè)文件是否找到、在哪找到。admin 的樣式就是通過這條命令驗(yàn)證的因?yàn)闆]人想在收集完才發(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ì)沒哈希的文件緩存時(shí)間別設(shè)那么長(zhǎng)否則改代碼后用戶還死死抱著舊文件。5.3 驗(yàn)證清單上線前值得跑一遍的檢查我每次上線前都會(huì)強(qiáng)制自己過一遍這一串檢查建議你也保存下來ls $STATIC_ROOT/myapp/css/確認(rèn)文件真實(shí)存在。瀏覽器打開/static/myapp/css/app.css確認(rèn) HTTP 狀態(tài)是 200 而不是 404。打開前端頁面按 F12看 Network 面板中 CSS/JS 的請(qǐng)求 URL 是否吻合構(gòu)建產(chǎn)物中的引用路徑。訪問 Django admin 頁面確認(rèn)后臺(tái)樣式加載正常。python manage.py check --deploy讓 Django 替你做一遍生產(chǎn)環(huán)境安全配置的三方審查靜態(tài)文件相關(guān)告警能提前暴露不少隱患。這套驗(yàn)證做完我基本可以放心地切換到生產(chǎn)模式。你可能會(huì)覺得麻煩但上線后如果讓用戶先碰見問題那才是真麻煩。6. 常見問題速查表與避坑心得6.1 我踩過的典型故障明細(xì)表我把自己這幾年處理過的、與這三件事相關(guān)的典型故障整理成了速查表你可以直接對(duì)照參考癥狀可能原因排查與解決頁面 HTML 有的CSS/JS 全 404前端 base/publicPath 與STATIC_URL不一致打開dist/index.html檢查引用路徑確認(rèn)base和STATIC_URL匹配CSS/JS 能訪問admin 后臺(tái)樣式全丟collectstatic前未收集 admin 靜態(tài)文件或 Nginx 未將/static/指向STATIC_ROOT跑python manage.py findstatic admin/css/base.css驗(yàn)證來源collectstatic后文件還是舊的前端沒有重新構(gòu)建或沒帶--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無寫權(quán)限使用RUN mkdir -p和RUN chown給運(yùn)行用戶分配權(quán)限或先手動(dòng)建目錄生產(chǎn)環(huán)境頁面樣式狂轉(zhuǎn)后端 API 正常ManifestStaticFilesStorage開啟后manifest.json缺失先完整跑一遍collectstatic確認(rèn)staticfiles.json生成或暫時(shí)改回默認(rèn) storage依賴安裝報(bào)錯(cuò)報(bào)某個(gè)包無法編譯環(huán)境缺少編譯工具鏈node-gyp等按官方文檔安裝 Python 和 VS Build Tools 對(duì)應(yīng)版本或嘗試使用預(yù)編譯二進(jìn)制版本這七類問題加起來基本覆蓋了我這些年看到的大部分部署事故。你會(huì)發(fā)現(xiàn)它們的根子全都指向一件事靜態(tài)文件在哪個(gè)環(huán)節(jié)斷了整個(gè)鏈路就斷了。6.2 三個(gè)被反復(fù)翻出來的避坑心得第一個(gè)心得我反復(fù)強(qiáng)調(diào)都不嫌多把開發(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è)約定一旦定下來后續(xù)所有運(yùn)營(yíng)、更換域名、接 CDN 都會(huì)輕松很多。越晚改越痛我就是從這種痛里爬出來的。第三個(gè)心得部署流程必須腳本化。我個(gè)人的做法是項(xiàng)目里放一個(gè)deploy.sh把git pull、依賴安裝、前端構(gòu)建、遷移、收集靜態(tài)文件全部串起來團(tuán)隊(duì)任何人都可以一鍵執(zhí)行。沒有腳本化的部署靠記性、靠手打、靠人肉檢查遲早會(huì)出岔子。真實(shí)環(huán)境里出岔子的那天往往就是老板在旁邊盯著的那天。最后分享點(diǎn)個(gè)人的操作體會(huì)這三個(gè)動(dòng)作我原本也是拆開做的后來發(fā)現(xiàn)只要把它們當(dāng)成一套標(biāo)準(zhǔn)流水線、寫進(jìn)部署腳本、配合版本鎖定整個(gè)上線過程完全可以做到無腦且可重復(fù)。再給我一次機(jī)會(huì)我會(huì)在項(xiàng)目第一天就把這套流程搭起來而不是等上線前才慌忙補(bǔ)救。這個(gè)習(xí)慣真的能幫你省下無數(shù)個(gè)加班之夜。