境搭建到避坑實踐)
簡介這是一份面向初學者的Python Django入門級Web工程源碼覆蓋用戶登錄、頁面渲染、SQLite數(shù)據(jù)存儲等基礎功能適合剛接觸Django框架或希望快速搭建Web應用起點的開發(fā)者參考也可作為課程設計或畢業(yè)設計的項目底稿。壓縮包共40個文件以13個py源碼文件與24個pyc編譯文件為主另含HTML頁面模板、txt運行說明與sqlite3數(shù)據(jù)庫整體僅155KB體量小、結(jié)構(gòu)清晰。目前已有480人學習下載。通過閱讀核心配置、路由、視圖與模型等模塊可以理清Django的MTV分層、路由映射與請求處理流程結(jié)合頁面模板目錄與SQLite數(shù)據(jù)庫能夠直接運行并體驗用戶登錄與頁面渲染的完整鏈路為后續(xù)擴展功能奠定基礎。1. 為什么“簡單Django項目”反而最考驗設計功力拿到一個“基于Python的簡單Django Web項目設計源碼”時不少人第一反應是Django 不是有startproject一鍵生成骨架嗎怎么還需要“設計”但恰恰是這個“簡單”二字最能區(qū)分一個人是背過教程還是真正寫過項目。我見過太多初學者把教程里的投票應用跑通后換一個需求就不知道怎么組織文件、怎么改配置、怎么讓多個頁面共用一份布局。所謂“設計源碼”真正的門檻不在 Django 本身而在于你如何用最小的文件數(shù)量搭出一個結(jié)構(gòu)清晰、能繼續(xù)迭代的 Web 項目。這篇文章會從一個最簡單的任務管理應用入手帶你完整走過環(huán)境搭建、項目骨架、視圖與模板協(xié)作、數(shù)據(jù)庫遷移的全過程并把我在實際開發(fā)中踩過的坑一并交代清楚。如果你是剛學完 Django 基礎、想獨立完成一個小項目卻不知道從哪下手的開發(fā)者這篇內(nèi)容正好對癥如果你已經(jīng)寫過幾個項目也可以重點看第五章的避坑清單那些問題幾乎每個項目都會遇到。2. 環(huán)境準備用虛擬環(huán)境隔離你的第一個 Django 項目2.1 環(huán)境創(chuàng)建的三個必做步驟動手寫 Django 項目之前環(huán)境隔離是第一道防線。很多初學者圖省事直接在全局環(huán)境里pip install django結(jié)果不同項目依賴的 Django 版本互相打架最后只能重裝 Python。常見的做法是用venv為每個項目建立獨立的 Python 環(huán)境這樣項目的依賴清單清晰別人拿到你的源碼后也能按requirements.txt一鍵復現(xiàn)。# 創(chuàng)建項目目錄并進入 mkdir django-todo cd django-todo # 創(chuàng)建虛擬環(huán)境venv 是 Python 3.3 自帶不需要額外安裝 python -m venv venv # 激活虛擬環(huán)境Windows 與 macOS/Linux 命令不同 # Windows: venv\Scripts\activate # macOS / Linux: source venv/bin/activate # 安裝 Django這里固定主版本避免后續(xù)升級帶來不可控變化 pip install django4.2.* # 生成依賴清單方便別人復現(xiàn)你的環(huán)境 pip freeze requirements.txt這段命令里有兩個關鍵點需要注意。第一venv目錄必須和項目代碼放在同一層級并在提交源碼時通過.gitignore把它排除掉否則別人 clone 下來會帶著一堆無用的本機文件。第二requirements.txt是“設計源碼”的一部分它記錄了項目的依賴底線沒有這個文件你的代碼在其他機器上大概率跑不起來。環(huán)境激活后建議順手驗證一下安裝結(jié)果。python -m django --version能看到具體版本號確認無誤后再進行下一步。如果你用的是 Anaconda 或 pyenv原理相同核心目標只有一個讓這個項目的依賴與系統(tǒng)全局環(huán)境徹底隔離。2.2 項目骨架與“設計源碼”的對應關系環(huán)境就緒后接下來是用django-admin生成項目骨架。這里我一般會先建一個項目級的配置目錄再創(chuàng)建一個應用目錄兩個步驟分開做讓配置與業(yè)務代碼各歸其位。# 生成項目配置目錄項目名用 config避免與業(yè)務模塊重名 django-admin startproject config . # 創(chuàng)建業(yè)務應用todo 是應用名代表“任務管理”這個業(yè)務模塊 python manage.py startapp todo # 查看生成的目錄結(jié)構(gòu) tree .執(zhí)行完這兩條命令后你會看到config目錄下是項目的全局配置settings.py、urls.py 等todo目錄下是業(yè)務代碼models.py、views.py、migrations 等。頂層還有一個manage.py它是所有 Django 管理命令的入口。這個結(jié)構(gòu)對“設計源碼”來說有一個重要含義config管“這個網(wǎng)站是什么”todo管“這個網(wǎng)站能做什么”。之所以把項目配置目錄命名為config而不是默認的mysite是因為默認名稱在后續(xù) import 時容易與業(yè)務模塊產(chǎn)生歧義。比如你建一個應用叫site再有一個全局目錄也叫siteimport 時就會互相干擾。用config是社區(qū)里比較普遍的做法團隊協(xié)作時也容易一眼分清職責邊界。此時項目還不能運行任何業(yè)務頁面但骨架已經(jīng)完整。你可以先跑一次python manage.py runserver瀏覽器訪問http://127.0.0.1:8000看到 Django 的默認歡迎頁就說明環(huán)境與骨架都正常。3. 核心文件逐個拆從 settings.py 到 urls.py 的配置要點3.1 settings.py新手最容易忽略的三個安全配置settings.py是整個項目的配置中心。新手往往只改INSTALLED_APPS和DATABASES卻忽略三個直接影響開發(fā)效率與安全性的配置項ALLOWED_HOSTS、LANGUAGE_CODE與TIME_ZONE、STATIC_URL。# config/settings.py # 允許訪問的主機列表。開發(fā)環(huán)境先留空或填 localhost # 部署時必須改成你的域名或服務器 IP否則訪問直接報 400。 ALLOWED_HOSTS [localhost, 127.0.0.1] # 語言與時區(qū)改為中文和上海時區(qū)避免后續(xù) datetime 顯示偏差 LANGUAGE_CODE zh-hans TIME_ZONE Asia/Shanghai # 靜態(tài)文件 URL 前綴。模板里用 {% static %} 時最終渲染出的路徑 # 就是 STATIC_URL 文件相對路徑。 STATIC_URL static/第一個配置ALLOWED_HOSTS是新手最容易“翻車”的地方。本地開發(fā)時用127.0.0.1沒問題但如果你用手機或局域網(wǎng) IP 訪問項目Django 會直接拒絕請求報DisallowedHost錯誤。原因就是 Django 默認只允許ALLOWED_HOSTS列表里的主機訪問。把局域網(wǎng) IP 加進列表即可解決。第二個配置是LANGUAGE_CODE和TIME_ZONE。Django 默認語言是英文時區(qū)是 UTC。如果你不做修改Django Admin 后臺全是英文而且datetime.now()獲取到的時間會比北京時間慢 8 小時。這個坑在后文第五節(jié)會專門展開。第三個配置是STATIC_URL。它決定模板中靜態(tài)文件的請求前綴。很多人把 CSS、JS 文件放到項目根目錄就完事結(jié)果頁面樣式死活不加載就是因為沒有同時配置靜態(tài)文件查找路徑。開發(fā)環(huán)境最簡單的做法是在設置里追加一行STATICFILES_DIRS把項目根目錄下的static文件夾加入查找范圍。3.2 urls.py 與應用級路由的分層設計Django 的路由設計講究“項目級路由分發(fā)應用級路由收口”。項目級urls.py只負責把不同應用的請求分發(fā)到對應模塊具體路徑由應用內(nèi)部自己管理。這樣做的好處是一個大型項目幾十個應用每個應用都能獨立調(diào)整路徑不用反復改動頂級路由文件。# config/urls.py項目級路由 from django.contrib import admin from django.urls import path, include urlpatterns [ # Django Admin 自帶的路由暫時保留 path(admin/, admin.site.urls), # 所有以 todo/ 開頭的請求交給 todo 應用自己的 urls.py 處理 path(todo/, include(todo.urls)), ]# todo/urls.py應用級路由需要手動創(chuàng)建 from django.urls import path from . import views urlpatterns [ # 訪問 /todo/ 時調(diào)用 views 里的 task_list 視圖函數(shù) path(, views.task_list, nametask_list), ]這里要解釋一下nametask_list的作用它是這條路由的“別名”。模板中可以用{% url task_list %}直接根據(jù)名稱生成 URL而不是硬編碼/todo/。當你改了路徑只需調(diào)整urls.py模板無需任何改動。這種設計在源碼閱讀時尤其重要——別人拿到你的項目通過name就能快速追蹤頁面邏輯。我在一個模擬項目X中見過反面教材所有路由全部寫在項目級urls.py里應用一多幾百行的路由文件根本沒法維護。每次加一個功能都要在那個龐然大物里搜半天。分層路由的設計從項目第一天就立好規(guī)矩后續(xù)擴展才不會失控。4. 讓頁面真正跑起來視圖、模板與靜態(tài)資源的協(xié)作4.1 視圖函數(shù)的最簡形態(tài)與上下文傳參視圖是 Django 處理請求的核心邏輯單元。一個最簡單的視圖函數(shù)接收request對象返回render渲染后的模板響應。以任務管理應用為例我們希望首頁能顯示所有任務記錄。# todo/views.py from django.shortcuts import render from .models import Task def task_list(request): # 從數(shù)據(jù)庫取出所有任務按創(chuàng)建時間倒序排列 tasks Task.objects.all().order_by(-created_at) # 把任務列表放進模板上下文模板里通過 tasks 變量訪問 return render(request, todo/task_list.html, {tasks: tasks})這里的邏輯可以拆成兩部分理解。第一行查詢Task.objects.all()會執(zhí)行SELECT * FROM task之類的 SQL 語句.order_by(-created_at)表示按創(chuàng)建時間倒序減號前綴代表反向排序。然后把查詢結(jié)果字典傳給render函數(shù)第三個參數(shù)就是模板上下文。模板上下文的概念值得多說一句Django 模板只認字典形式的上下文鍵名就是模板里可用的變量名。這里傳了{tasks: tasks}模板里就能用{% for task in tasks %}遍歷任務。如果你傳的是一個對象而不是字典模板直接報錯。4.2 模板繼承與靜態(tài)文件的路徑配置模板文件放在應用目錄下的templates文件夾里但有一個容易繞暈的細節(jié)Django 在多個應用間查找模板時會按INSTALLED_APPS順序搜索如果你的兩個應用都有同名模板后加載的應用會覆蓋先加載的。為了避免這種“模板污染”規(guī)范做法是在應用下的templates目錄里再套一層與應用同名的子目錄。!-- todo/templates/todo/task_list.html -- {% extends base.html %} {% block content %} div classcontainer h1我的任務清單/h1 ul {% for task in tasks %} li{{ task.title }} - {% if task.done %}已完成{% else %}待完成{% endif %}/li {% empty %} li還沒有任務去添加一個吧。/li {% endfor %} /ul /div {% endblock %}!-- templates/base.html項目級通用模板 -- !DOCTYPE html html langzh-hans head meta charsetUTF-8 title{% block title %}任務管理{% endblock %}/title !-- 通過 static 標簽引用 CSS 文件 -- {% load static %} link relstylesheet href{% static css/style.css %} /head body main {% block content %} {% endblock %} /main /body /htmlbase.html是全局布局模板task_list.html通過{% extends base.html %}繼承它并用{% block content %}填充頁面主體。這種設計讓公共的導航、頁腳、CSS 引用只寫一次每個頁面只需關心自己的內(nèi)容塊。這里大概率會遇到一個經(jīng)典問題CSS 文件放在哪個目錄答案是你的項目根目錄下建一個static目錄然后在settings.py里配置STATICFILES_DIRS。沒有這個配置{% static %}標簽會報TemplateSyntaxError頁面樣式全丟。# config/settings.py 追加 STATICFILES_DIRS [ BASE_DIR / static, ]配置完成后把style.css放到static/css/下刷新頁面就能看到樣式生效。整個視圖、模板、靜態(tài)文件的協(xié)作路徑就打通了。5. Django 項目避坑5 個高頻“翻車”現(xiàn)場與排查方法5.1 遷移報錯表已存在卻無法關聯(lián)現(xiàn)象運行python manage.py makemigrations提示No changes detected但數(shù)據(jù)庫中根本沒有對應的表。原因最常見的情況是你手動刪過數(shù)據(jù)庫文件或者把 app 的migrations目錄清空過。Django 通過遷移記錄文件追蹤模型變化記錄與數(shù)據(jù)庫不一致時就會“失憶”。解決先確認 app 是否真的加入INSTALLED_APPS再刪掉數(shù)據(jù)庫和migrations目錄中的所有文件init.py 除外然后重新執(zhí)行makemigrations和migrate。不要保留任何舊的遷移記錄。5.2 靜態(tài)文件 404開發(fā)環(huán)境與生產(chǎn)環(huán)境姿勢完全不同現(xiàn)象本地開發(fā)時頁面樣式加載正常換成runserver 0.0.0.0:8000通過局域網(wǎng) IP 訪問CSS 全部 404。原因runserver在默認DEBUGTrue時才會自動托管靜態(tài)文件。當你用0.0.0.0啟動Django 仍然會處理靜態(tài)文件請求但瀏覽器請求地址變成了http://局域網(wǎng)IP:8000/static/css/style.css如果ALLOWED_HOSTS沒有把該 IP 加進去請求會被拒絕。解決把局域網(wǎng) IP 加進ALLOWED_HOSTS同時確認STATIC_URL與STATICFILES_DIRS配置正確。生產(chǎn)環(huán)境則必須用collectstatic把靜態(tài)文件收集到指定目錄再由 Nginx 托管Django 本身不負責生產(chǎn)環(huán)境的靜態(tài)文件服務。5.3 時區(qū)與 datetime.now() 的“玄學”偏差現(xiàn)象任務創(chuàng)建時間顯示比當前時間慢了 8 小時或者 Admin 后臺時間與本地時間不一致。原因settings.py里TIME_ZONE沒改成Asia/Shanghai同時USE_TZ為True時數(shù)據(jù)庫存的是 UTC 時間展示時沒有做時區(qū)轉(zhuǎn)換。解決把TIME_ZONE Asia/Shanghai和LANGUAGE_CODE zh-hans配置好。如果你不想處理時區(qū)轉(zhuǎn)換的復雜度可以把USE_TZ FalseDjango 就會直接使用本地時間不再做 UTC 轉(zhuǎn)換。但要注意USE_TZ False后所有涉及時間的邏輯都要多留個心建議還是規(guī)范使用USE_TZ True。5.4 CSRF 驗證失敗表單提交被攔的真相現(xiàn)象在模板里寫了一個form methodpost提交時報CSRF verification failed。原因Django 默認開啟 CSRF 防護所有 POST 請求必須帶上 CSRF token。模板里忘記加{% csrf_token %}標簽或者使用了 Ajax 但沒有在請求頭中攜帶 token都會被攔截。解決在模板表單內(nèi)加入{% csrf_token %}。Ajax 請求則在 JavaScript 中從 cookie 讀取csrftoken然后寫入請求頭X-CSRFToken。記住一點凡是 POST 請求必須通過某種方式攜帶 CSRF token。5.5 ALLOWED_HOSTS換 IP 訪問就報錯的排查路徑現(xiàn)象本地用127.0.0.1:8000一切正常手機通過局域網(wǎng) IP 訪問時頁面提示DisallowedHost。原因ALLOWED_HOSTS列表只包含localhost和127.0.0.1局域網(wǎng) IP 不在允許范圍。Django 出于安全考慮默認拒絕所有未列入白名單的主機訪問。解決把當前機器的局域網(wǎng) IP例如192.168.1.100加入ALLOWED_HOSTS然后重啟runserver。如果只是臨時調(diào)試可以直接設置ALLOWED_HOSTS [*]但不建議長期這么做。6. 從“能跑”到“能看”用一個 Bootstrap 模板給項目加分6.1 用模板繼承改造現(xiàn)有頁面“設計源碼”如果只是功能跑通遠遠不夠。一個能拿得出手的項目至少得有一套看得過去的界面。最快的方式是引入現(xiàn)成的 CSS 框架這里以 Bootstrap 為例進行改造。!-- templates/base.html改造后 -- !DOCTYPE html html langzh-hans head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title{% block title %}任務管理{% endblock %}/title !-- 直接引用 public CDN省去本地靜態(tài)文件配置 -- link hrefhttps://cdn.jsdelivr.net/npm/bootstrap5.3.3/dist/css/bootstrap.min.css relstylesheet {% block extra_head %}{% endblock %} /head body classbg-light nav classnavbar navbar-expand-lg navbar-dark bg-primary div classcontainer a classnavbar-brand href{% url task_list %}任務管理/a /div /nav main classcontainer py-4 {% block content %}{% endblock %} /main /body /html改造后的base.html引入了 Bootstrap 的公共 CDN內(nèi)容分發(fā)網(wǎng)絡即把靜態(tài)資源放在第三方服務器上用戶訪問時從就近節(jié)點加載速度更快且不占用你的服務器流量。這樣做的好處是項目不需要下載維護一份 Bootstrap 源文件模板可以直接使用 Bootstrap 的類名。注意一個細節(jié)CDN 方式只適合開發(fā)階段或?qū)虞d速度不敏感的場景。正式部署到內(nèi)網(wǎng)或生產(chǎn)環(huán)境最好把 Bootstrap 文件下載到項目的static目錄下避免外網(wǎng)中斷導致樣式全崩。6.2 學會這個排查習慣省掉一半調(diào)試時間最后一個技巧也是我每次項目必用的排查習慣開啟 Django 的 Debug 日志輸出。在settings.py里配置一個簡單的日志字典Django 會把你所有 SQL 查詢、頁面渲染耗時、異常堆棧全部打印在控制臺。遇到“頁面空白”“數(shù)據(jù)不對”這類問題先看日志不要盲目改代碼。# config/settings.py 追加日志配置 LOGGING { version: 1, disable_existing_loggers: False, handlers: { console: { class: logging.StreamHandler, }, }, loggers: { # 打印所有 SQL 語句排查數(shù)據(jù)庫查詢問題非常有效 django.db.backends: { handlers: [console], level: DEBUG, }, }, }我自己的習慣是項目出現(xiàn)任何異常第一件事不是打開源碼而是看終端輸出。SQL 日志能告訴你 Django 到底執(zhí)行了什么查詢、查詢了幾次。比如頁面加載慢看到django.db.backends日志里一個頁面觸發(fā)了 50 條 SQL馬上就能判斷是 N1 查詢問題然后去優(yōu)化 ORM 邏輯。這個習慣幫我省過無數(shù)個小時的排查時間。哪怕現(xiàn)在寫一個“簡單”項目我也會從第一天就把日志配好。一個整潔、可觀測的開發(fā)環(huán)境比多寫幾個功能更能體現(xiàn)一個開發(fā)者的成熟度。希望這些內(nèi)容能幫你把 Django 項目從“能跑”推進到“能看、能維護”少走我當年走過的彎路。本文還有配套的精品資源點擊獲取 簡單Django Web項目設計全攻略：從環(huán)境搭建到避坑實踐
簡介這是一份面向初學者的Python Django入門級Web工程源碼覆蓋用戶登錄、頁面渲染、SQLite數(shù)據(jù)存儲等基礎功能適合剛接觸Django框架或希望快速搭建Web應用起點的開發(fā)者參考也可作為課程設計或畢業(yè)設計的項目底稿。壓縮包共40個文件以13個py源碼文件與24個pyc編譯文件為主另含HTML頁面模板、txt運行說明與sqlite3數(shù)據(jù)庫整體僅155KB體量小、結(jié)構(gòu)清晰。目前已有480人學習下載。通過閱讀核心配置、路由、視圖與模型等模塊可以理清Django的MTV分層、路由映射與請求處理流程結(jié)合頁面模板目錄與SQLite數(shù)據(jù)庫能夠直接運行并體驗用戶登錄與頁面渲染的完整鏈路為后續(xù)擴展功能奠定基礎。1. 為什么“簡單Django項目”反而最考驗設計功力拿到一個“基于Python的簡單Django Web項目設計源碼”時不少人第一反應是Django 不是有startproject一鍵生成骨架嗎怎么還需要“設計”但恰恰是這個“簡單”二字最能區(qū)分一個人是背過教程還是真正寫過項目。我見過太多初學者把教程里的投票應用跑通后換一個需求就不知道怎么組織文件、怎么改配置、怎么讓多個頁面共用一份布局。所謂“設計源碼”真正的門檻不在 Django 本身而在于你如何用最小的文件數(shù)量搭出一個結(jié)構(gòu)清晰、能繼續(xù)迭代的 Web 項目。這篇文章會從一個最簡單的任務管理應用入手帶你完整走過環(huán)境搭建、項目骨架、視圖與模板協(xié)作、數(shù)據(jù)庫遷移的全過程并把我在實際開發(fā)中踩過的坑一并交代清楚。如果你是剛學完 Django 基礎、想獨立完成一個小項目卻不知道從哪下手的開發(fā)者這篇內(nèi)容正好對癥如果你已經(jīng)寫過幾個項目也可以重點看第五章的避坑清單那些問題幾乎每個項目都會遇到。2. 環(huán)境準備用虛擬環(huán)境隔離你的第一個 Django 項目2.1 環(huán)境創(chuàng)建的三個必做步驟動手寫 Django 項目之前環(huán)境隔離是第一道防線。很多初學者圖省事直接在全局環(huán)境里pip install django結(jié)果不同項目依賴的 Django 版本互相打架最后只能重裝 Python。常見的做法是用venv為每個項目建立獨立的 Python 環(huán)境這樣項目的依賴清單清晰別人拿到你的源碼后也能按requirements.txt一鍵復現(xiàn)。# 創(chuàng)建項目目錄并進入 mkdir django-todo cd django-todo # 創(chuàng)建虛擬環(huán)境venv 是 Python 3.3 自帶不需要額外安裝 python -m venv venv # 激活虛擬環(huán)境Windows 與 macOS/Linux 命令不同 # Windows: venv\Scripts\activate # macOS / Linux: source venv/bin/activate # 安裝 Django這里固定主版本避免后續(xù)升級帶來不可控變化 pip install django4.2.* # 生成依賴清單方便別人復現(xiàn)你的環(huán)境 pip freeze requirements.txt這段命令里有兩個關鍵點需要注意。第一venv目錄必須和項目代碼放在同一層級并在提交源碼時通過.gitignore把它排除掉否則別人 clone 下來會帶著一堆無用的本機文件。第二requirements.txt是“設計源碼”的一部分它記錄了項目的依賴底線沒有這個文件你的代碼在其他機器上大概率跑不起來。環(huán)境激活后建議順手驗證一下安裝結(jié)果。python -m django --version能看到具體版本號確認無誤后再進行下一步。如果你用的是 Anaconda 或 pyenv原理相同核心目標只有一個讓這個項目的依賴與系統(tǒng)全局環(huán)境徹底隔離。2.2 項目骨架與“設計源碼”的對應關系環(huán)境就緒后接下來是用django-admin生成項目骨架。這里我一般會先建一個項目級的配置目錄再創(chuàng)建一個應用目錄兩個步驟分開做讓配置與業(yè)務代碼各歸其位。# 生成項目配置目錄項目名用 config避免與業(yè)務模塊重名 django-admin startproject config . # 創(chuàng)建業(yè)務應用todo 是應用名代表“任務管理”這個業(yè)務模塊 python manage.py startapp todo # 查看生成的目錄結(jié)構(gòu) tree .執(zhí)行完這兩條命令后你會看到config目錄下是項目的全局配置settings.py、urls.py 等todo目錄下是業(yè)務代碼models.py、views.py、migrations 等。頂層還有一個manage.py它是所有 Django 管理命令的入口。這個結(jié)構(gòu)對“設計源碼”來說有一個重要含義config管“這個網(wǎng)站是什么”todo管“這個網(wǎng)站能做什么”。之所以把項目配置目錄命名為config而不是默認的mysite是因為默認名稱在后續(xù) import 時容易與業(yè)務模塊產(chǎn)生歧義。比如你建一個應用叫site再有一個全局目錄也叫siteimport 時就會互相干擾。用config是社區(qū)里比較普遍的做法團隊協(xié)作時也容易一眼分清職責邊界。此時項目還不能運行任何業(yè)務頁面但骨架已經(jīng)完整。你可以先跑一次python manage.py runserver瀏覽器訪問http://127.0.0.1:8000看到 Django 的默認歡迎頁就說明環(huán)境與骨架都正常。3. 核心文件逐個拆從 settings.py 到 urls.py 的配置要點3.1 settings.py新手最容易忽略的三個安全配置settings.py是整個項目的配置中心。新手往往只改INSTALLED_APPS和DATABASES卻忽略三個直接影響開發(fā)效率與安全性的配置項ALLOWED_HOSTS、LANGUAGE_CODE與TIME_ZONE、STATIC_URL。# config/settings.py # 允許訪問的主機列表。開發(fā)環(huán)境先留空或填 localhost # 部署時必須改成你的域名或服務器 IP否則訪問直接報 400。 ALLOWED_HOSTS [localhost, 127.0.0.1] # 語言與時區(qū)改為中文和上海時區(qū)避免后續(xù) datetime 顯示偏差 LANGUAGE_CODE zh-hans TIME_ZONE Asia/Shanghai # 靜態(tài)文件 URL 前綴。模板里用 {% static %} 時最終渲染出的路徑 # 就是 STATIC_URL 文件相對路徑。 STATIC_URL static/第一個配置ALLOWED_HOSTS是新手最容易“翻車”的地方。本地開發(fā)時用127.0.0.1沒問題但如果你用手機或局域網(wǎng) IP 訪問項目Django 會直接拒絕請求報DisallowedHost錯誤。原因就是 Django 默認只允許ALLOWED_HOSTS列表里的主機訪問。把局域網(wǎng) IP 加進列表即可解決。第二個配置是LANGUAGE_CODE和TIME_ZONE。Django 默認語言是英文時區(qū)是 UTC。如果你不做修改Django Admin 后臺全是英文而且datetime.now()獲取到的時間會比北京時間慢 8 小時。這個坑在后文第五節(jié)會專門展開。第三個配置是STATIC_URL。它決定模板中靜態(tài)文件的請求前綴。很多人把 CSS、JS 文件放到項目根目錄就完事結(jié)果頁面樣式死活不加載就是因為沒有同時配置靜態(tài)文件查找路徑。開發(fā)環(huán)境最簡單的做法是在設置里追加一行STATICFILES_DIRS把項目根目錄下的static文件夾加入查找范圍。3.2 urls.py 與應用級路由的分層設計Django 的路由設計講究“項目級路由分發(fā)應用級路由收口”。項目級urls.py只負責把不同應用的請求分發(fā)到對應模塊具體路徑由應用內(nèi)部自己管理。這樣做的好處是一個大型項目幾十個應用每個應用都能獨立調(diào)整路徑不用反復改動頂級路由文件。# config/urls.py項目級路由 from django.contrib import admin from django.urls import path, include urlpatterns [ # Django Admin 自帶的路由暫時保留 path(admin/, admin.site.urls), # 所有以 todo/ 開頭的請求交給 todo 應用自己的 urls.py 處理 path(todo/, include(todo.urls)), ]# todo/urls.py應用級路由需要手動創(chuàng)建 from django.urls import path from . import views urlpatterns [ # 訪問 /todo/ 時調(diào)用 views 里的 task_list 視圖函數(shù) path(, views.task_list, nametask_list), ]這里要解釋一下nametask_list的作用它是這條路由的“別名”。模板中可以用{% url task_list %}直接根據(jù)名稱生成 URL而不是硬編碼/todo/。當你改了路徑只需調(diào)整urls.py模板無需任何改動。這種設計在源碼閱讀時尤其重要——別人拿到你的項目通過name就能快速追蹤頁面邏輯。我在一個模擬項目X中見過反面教材所有路由全部寫在項目級urls.py里應用一多幾百行的路由文件根本沒法維護。每次加一個功能都要在那個龐然大物里搜半天。分層路由的設計從項目第一天就立好規(guī)矩后續(xù)擴展才不會失控。4. 讓頁面真正跑起來視圖、模板與靜態(tài)資源的協(xié)作4.1 視圖函數(shù)的最簡形態(tài)與上下文傳參視圖是 Django 處理請求的核心邏輯單元。一個最簡單的視圖函數(shù)接收request對象返回render渲染后的模板響應。以任務管理應用為例我們希望首頁能顯示所有任務記錄。# todo/views.py from django.shortcuts import render from .models import Task def task_list(request): # 從數(shù)據(jù)庫取出所有任務按創(chuàng)建時間倒序排列 tasks Task.objects.all().order_by(-created_at) # 把任務列表放進模板上下文模板里通過 tasks 變量訪問 return render(request, todo/task_list.html, {tasks: tasks})這里的邏輯可以拆成兩部分理解。第一行查詢Task.objects.all()會執(zhí)行SELECT * FROM task之類的 SQL 語句.order_by(-created_at)表示按創(chuàng)建時間倒序減號前綴代表反向排序。然后把查詢結(jié)果字典傳給render函數(shù)第三個參數(shù)就是模板上下文。模板上下文的概念值得多說一句Django 模板只認字典形式的上下文鍵名就是模板里可用的變量名。這里傳了{tasks: tasks}模板里就能用{% for task in tasks %}遍歷任務。如果你傳的是一個對象而不是字典模板直接報錯。4.2 模板繼承與靜態(tài)文件的路徑配置模板文件放在應用目錄下的templates文件夾里但有一個容易繞暈的細節(jié)Django 在多個應用間查找模板時會按INSTALLED_APPS順序搜索如果你的兩個應用都有同名模板后加載的應用會覆蓋先加載的。為了避免這種“模板污染”規(guī)范做法是在應用下的templates目錄里再套一層與應用同名的子目錄。!-- todo/templates/todo/task_list.html -- {% extends base.html %} {% block content %} div classcontainer h1我的任務清單/h1 ul {% for task in tasks %} li{{ task.title }} - {% if task.done %}已完成{% else %}待完成{% endif %}/li {% empty %} li還沒有任務去添加一個吧。/li {% endfor %} /ul /div {% endblock %}!-- templates/base.html項目級通用模板 -- !DOCTYPE html html langzh-hans head meta charsetUTF-8 title{% block title %}任務管理{% endblock %}/title !-- 通過 static 標簽引用 CSS 文件 -- {% load static %} link relstylesheet href{% static css/style.css %} /head body main {% block content %} {% endblock %} /main /body /htmlbase.html是全局布局模板task_list.html通過{% extends base.html %}繼承它并用{% block content %}填充頁面主體。這種設計讓公共的導航、頁腳、CSS 引用只寫一次每個頁面只需關心自己的內(nèi)容塊。這里大概率會遇到一個經(jīng)典問題CSS 文件放在哪個目錄答案是你的項目根目錄下建一個static目錄然后在settings.py里配置STATICFILES_DIRS。沒有這個配置{% static %}標簽會報TemplateSyntaxError頁面樣式全丟。# config/settings.py 追加 STATICFILES_DIRS [ BASE_DIR / static, ]配置完成后把style.css放到static/css/下刷新頁面就能看到樣式生效。整個視圖、模板、靜態(tài)文件的協(xié)作路徑就打通了。5. Django 項目避坑5 個高頻“翻車”現(xiàn)場與排查方法5.1 遷移報錯表已存在卻無法關聯(lián)現(xiàn)象運行python manage.py makemigrations提示No changes detected但數(shù)據(jù)庫中根本沒有對應的表。原因最常見的情況是你手動刪過數(shù)據(jù)庫文件或者把 app 的migrations目錄清空過。Django 通過遷移記錄文件追蹤模型變化記錄與數(shù)據(jù)庫不一致時就會“失憶”。解決先確認 app 是否真的加入INSTALLED_APPS再刪掉數(shù)據(jù)庫和migrations目錄中的所有文件init.py 除外然后重新執(zhí)行makemigrations和migrate。不要保留任何舊的遷移記錄。5.2 靜態(tài)文件 404開發(fā)環(huán)境與生產(chǎn)環(huán)境姿勢完全不同現(xiàn)象本地開發(fā)時頁面樣式加載正常換成runserver 0.0.0.0:8000通過局域網(wǎng) IP 訪問CSS 全部 404。原因runserver在默認DEBUGTrue時才會自動托管靜態(tài)文件。當你用0.0.0.0啟動Django 仍然會處理靜態(tài)文件請求但瀏覽器請求地址變成了http://局域網(wǎng)IP:8000/static/css/style.css如果ALLOWED_HOSTS沒有把該 IP 加進去請求會被拒絕。解決把局域網(wǎng) IP 加進ALLOWED_HOSTS同時確認STATIC_URL與STATICFILES_DIRS配置正確。生產(chǎn)環(huán)境則必須用collectstatic把靜態(tài)文件收集到指定目錄再由 Nginx 托管Django 本身不負責生產(chǎn)環(huán)境的靜態(tài)文件服務。5.3 時區(qū)與 datetime.now() 的“玄學”偏差現(xiàn)象任務創(chuàng)建時間顯示比當前時間慢了 8 小時或者 Admin 后臺時間與本地時間不一致。原因settings.py里TIME_ZONE沒改成Asia/Shanghai同時USE_TZ為True時數(shù)據(jù)庫存的是 UTC 時間展示時沒有做時區(qū)轉(zhuǎn)換。解決把TIME_ZONE Asia/Shanghai和LANGUAGE_CODE zh-hans配置好。如果你不想處理時區(qū)轉(zhuǎn)換的復雜度可以把USE_TZ FalseDjango 就會直接使用本地時間不再做 UTC 轉(zhuǎn)換。但要注意USE_TZ False后所有涉及時間的邏輯都要多留個心建議還是規(guī)范使用USE_TZ True。5.4 CSRF 驗證失敗表單提交被攔的真相現(xiàn)象在模板里寫了一個form methodpost提交時報CSRF verification failed。原因Django 默認開啟 CSRF 防護所有 POST 請求必須帶上 CSRF token。模板里忘記加{% csrf_token %}標簽或者使用了 Ajax 但沒有在請求頭中攜帶 token都會被攔截。解決在模板表單內(nèi)加入{% csrf_token %}。Ajax 請求則在 JavaScript 中從 cookie 讀取csrftoken然后寫入請求頭X-CSRFToken。記住一點凡是 POST 請求必須通過某種方式攜帶 CSRF token。5.5 ALLOWED_HOSTS換 IP 訪問就報錯的排查路徑現(xiàn)象本地用127.0.0.1:8000一切正常手機通過局域網(wǎng) IP 訪問時頁面提示DisallowedHost。原因ALLOWED_HOSTS列表只包含localhost和127.0.0.1局域網(wǎng) IP 不在允許范圍。Django 出于安全考慮默認拒絕所有未列入白名單的主機訪問。解決把當前機器的局域網(wǎng) IP例如192.168.1.100加入ALLOWED_HOSTS然后重啟runserver。如果只是臨時調(diào)試可以直接設置ALLOWED_HOSTS [*]但不建議長期這么做。6. 從“能跑”到“能看”用一個 Bootstrap 模板給項目加分6.1 用模板繼承改造現(xiàn)有頁面“設計源碼”如果只是功能跑通遠遠不夠。一個能拿得出手的項目至少得有一套看得過去的界面。最快的方式是引入現(xiàn)成的 CSS 框架這里以 Bootstrap 為例進行改造。!-- templates/base.html改造后 -- !DOCTYPE html html langzh-hans head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title{% block title %}任務管理{% endblock %}/title !-- 直接引用 public CDN省去本地靜態(tài)文件配置 -- link hrefhttps://cdn.jsdelivr.net/npm/bootstrap5.3.3/dist/css/bootstrap.min.css relstylesheet {% block extra_head %}{% endblock %} /head body classbg-light nav classnavbar navbar-expand-lg navbar-dark bg-primary div classcontainer a classnavbar-brand href{% url task_list %}任務管理/a /div /nav main classcontainer py-4 {% block content %}{% endblock %} /main /body /html改造后的base.html引入了 Bootstrap 的公共 CDN內(nèi)容分發(fā)網(wǎng)絡即把靜態(tài)資源放在第三方服務器上用戶訪問時從就近節(jié)點加載速度更快且不占用你的服務器流量。這樣做的好處是項目不需要下載維護一份 Bootstrap 源文件模板可以直接使用 Bootstrap 的類名。注意一個細節(jié)CDN 方式只適合開發(fā)階段或?qū)虞d速度不敏感的場景。正式部署到內(nèi)網(wǎng)或生產(chǎn)環(huán)境最好把 Bootstrap 文件下載到項目的static目錄下避免外網(wǎng)中斷導致樣式全崩。6.2 學會這個排查習慣省掉一半調(diào)試時間最后一個技巧也是我每次項目必用的排查習慣開啟 Django 的 Debug 日志輸出。在settings.py里配置一個簡單的日志字典Django 會把你所有 SQL 查詢、頁面渲染耗時、異常堆棧全部打印在控制臺。遇到“頁面空白”“數(shù)據(jù)不對”這類問題先看日志不要盲目改代碼。# config/settings.py 追加日志配置 LOGGING { version: 1, disable_existing_loggers: False, handlers: { console: { class: logging.StreamHandler, }, }, loggers: { # 打印所有 SQL 語句排查數(shù)據(jù)庫查詢問題非常有效 django.db.backends: { handlers: [console], level: DEBUG, }, }, }我自己的習慣是項目出現(xiàn)任何異常第一件事不是打開源碼而是看終端輸出。SQL 日志能告訴你 Django 到底執(zhí)行了什么查詢、查詢了幾次。比如頁面加載慢看到django.db.backends日志里一個頁面觸發(fā)了 50 條 SQL馬上就能判斷是 N1 查詢問題然后去優(yōu)化 ORM 邏輯。這個習慣幫我省過無數(shù)個小時的排查時間。哪怕現(xiàn)在寫一個“簡單”項目我也會從第一天就把日志配好。一個整潔、可觀測的開發(fā)環(huán)境比多寫幾個功能更能體現(xiàn)一個開發(fā)者的成熟度。希望這些內(nèi)容能幫你把 Django 項目從“能跑”推進到“能看、能維護”少走我當年走過的彎路。本文還有配套的精品資源點擊獲取