簡介這是一份基于Python Flask框架搭建簡易個人博客網站的完整源碼與學習資料包。內容覆蓋應用初始化、路由視圖、Jinja2模板渲染、SQLAlchemy數據庫操作以及用戶登錄認證等核心知識點適合Web開發(fā)初學者和希望系統(tǒng)學習Flask實踐的人群。資源共19個文件包含12個HTML模板、2個JS交互腳本、2個Python程序文件另有CSS樣式、Markdown說明和文本依賴清單壓縮包僅71KB目錄結構清晰便于按模塊查看。目前已有5267人學習下載。代碼中提供了文章模型和表單處理邏輯讀者可在學習過程中理解靜態(tài)文件組織方式、父模板繼承和用戶會話管理思路并借助附帶的環(huán)境配置與運行說明快速復現一個具備內容發(fā)布能力的個人博客網站進一步擴展評論、分類、搜索等功能。1. 為什么「用 Flask 搭個人博客」依然是練手與落地的黃金項目這兩年前端框架鋪天蓋地靜態(tài)站生成器一鍵出圖很多人覺得個人博客沒必要再動后端。但如果你真想理解「瀏覽器請求到服務器響應中間發(fā)生了什么」或者你想把博客做成能登錄、能后臺發(fā)文、能根據關鍵詞搜索的完整小系統(tǒng)那么用 Flask 寫一個簡單博客依然是性價比最高的入門路徑也是進階到微服務前最值得親手敲一遍的「hello world」。很多人一上來就上重型框架結果是配置半天還沒看到一條文章。而 Flask 輕、快、生態(tài)夠用一個最小博客核心代碼不到三百行。它能解決的核心訴求是快速搭建、本地寫作、隨時備份——你不需要遷就任何現成平臺數據完全在自己手里。本文會從一個能跑的最小版本講起再把路由、數據庫、Markdown 渲染和部署里的坑逐個拆開讓你照著敲完能拿到一個真正每天手動寫文章、不會被靜態(tài)構建流程繞暈的博客系統(tǒng)。2. 先把地基打對Flask 項目的目錄拆分與虛擬環(huán)境2.1 為什么簡單項目也要拆目錄而不是一個 app.py 走天下新手最容易交出的作品是一個 app.py 里堆了所有路由、模型、模板和靜態(tài)文件路徑。這個方案在上傳幾十篇文章之后必然翻車改個數據庫字段要在一千行里找靜態(tài)文件路徑稍微一亂就 404想加接口測試又無處下手。所以我建議哪怕標題寫著「簡單」也按功能模塊拆開但不要拆過度——三層就夠入口文件、應用工廠、業(yè)務模塊。這樣既能滿足「簡單」又能讓結構和團隊里用 Django 或 Spring 的同事互相能看明白。一個我常用的最小布局是這樣的blog_demo/ ├── manage.py # 應用入口啟動跟數據庫初始化都在這 ├── requirements.txt # 依賴列表 ├── app/ │ ├── __init__.py # create_app 工廠函數 │ ├── models.py # 數據庫表模型 │ ├── views.py # 路由與業(yè)務邏輯 │ ├── templates/ # Jinja2 模板 │ │ ├── base.html │ │ ├── index.html │ │ └── post.html │ └── static/ # CSS 和少量 JS └── instance/ # 運行時生成的 sqlite 文件放這里很多人會質疑一個小博客需要這樣嗎常見做法是「先把路由放到 views模型放 models將來加新模塊就加一個 blueprint」。我在第一次重構時就把所有路由都集中在 views.py 里等寫到第三類功能就后悔了因為模板、表單、接口混在一起找一處改動要翻兩屏。即便你的項目只有 5 個路由拆成 factory 也能讓你在寫單測時輕松替換配置。2.2 虛擬環(huán)境與依賴鎖定給未來的自己留條后悔藥整個過程我一般會先準備虛擬環(huán)境原因很簡單Python 版本和依賴版本之間的兼容性問題是項目里最常見的玄學而 virtualenv 就是一道隔離墻。Flask 2.x 和 3.x 的 API 大體一致但如果你在系統(tǒng)全局環(huán)境里裝過其他框架的依賴很容易出現版本互相覆蓋的情況。python3 -m venv venv source venv/bin/activate # Windows 是 venv\Scripts\activate pip install flask flask-sqlalchemy python-dotenv pip freeze requirements.txt這條命令跑完后requirements.txt 里會把 Flask 和 SQLAlchemy 的精確版本記下來。之后在任何一臺機器上執(zhí)行 pip install -r requirements.txt就能還原出幾乎一致的環(huán)境。這里有一個我在真實項目中碰到的坑sqlite 和 Flask-SQLAlchemy 組合在 3.x 里部分接口行為有調整比如 db.engine 的創(chuàng)建方式直接按舊教程敲有時會報錯。所以依賴版本一定要鎖別偷懶用 號。從工廠函數開始寫入口才能保持干凈# app/__init__.py from flask import Flask from flask_sqlalchemy import SQLAlchemy db SQLAlchemy() def create_app(): app Flask(__name__) app.config[SQLALCHEMY_DATABASE_URI] sqlite:/// app.instance_path /blog.db app.config[SQLALCHEMY_TRACK_MODIFICATIONS] False db.init_app(app) # 注冊路由藍圖 from .views import bp as main_bp app.register_blueprint(main_bp) # 啟動時自動建表 with app.app_context(): db.create_all() return app這段代碼的關鍵點有兩個一是 SQLALCHEMY_DATABASE_URI 用了 instance 目錄這樣數據庫不會和代碼文件混在一起備份時直接拷貝 instance 就夠了二是db.init_app(app)是擴展與 app 解耦的標準寫法將來要換成 MySQL 連接串改動只在這一行。我見過有人把 db 直接掛在 app 上結果后面做單元測試時無法復用那就是給自己埋坑。create_all() 雖然很簡單但它只會創(chuàng)建不存在的表無法檢測字段變更所以它只適合起步階段。后面改模型時你需要遷移工具或手動刪表重建這一點心里有數就好。3. 數據模型與 SQLite 選型一張表也能撐起博客的骨架3.1 博客文章表該有哪些字段別一上來就過度設計一個簡單博客實際要用的表說實話一張就夠。那些做多用戶、多角色、評論、點贊的方案已經超出了「簡單」這個詞的范圍。做個人博客時通常就只需要記錄標題、別名slug、正文、摘要、分類、發(fā)布時間、更新時間。如果后面想加訪問統(tǒng)計再補字段就行一開始就把表設計復雜只會讓代碼量翻倍。我自己的經驗是字段的精髓在于「夠用 好遷移」。# app/models.py from datetime import datetime from . import db class Post(db.Model): __tablename__ post id db.Column(db.Integer, primary_keyTrue) title db.Column(db.String(120), nullableFalse) slug db.Column(db.String(120), uniqueTrue, nullableFalse, indexTrue) content db.Column(db.Text, nullableFalse) excerpt db.Column(db.String(300), default) category db.Column(db.String(50), default默認) created_at db.Column(db.DateTime, defaultdatetime.utcnow) updated_at db.Column(db.DateTime, defaultdatetime.utcnow, onupdatedatetime.utcnow) def __repr__(self): return fPost {self.title}這三個列值得解釋slug 用于 URL 友好鏈接比如訪問 /post/hello-world 而不是 /post/12既美觀又有利于記憶與分享excerpt 是列表頁的摘要從正文里截取則更省事但手動填寫能控制列表長度category 用字符串而不是單獨建表可以避免「為了簡單而復雜化」。datetime.utcnow會以 UTC 存取展示時在前端轉本地時間這是我在多端訪問時總結出的可靠習慣。如果直接用 now 存本地時間將來部署到云端服務器和本地各寫一次時區(qū)會讓你徹底崩潰。3.2 SQLite 到底扛不扛得住一個博客的日常訪問很多人擔心 SQLite 是不是太玩具真實部署會不會出問題。根據我實際跑過的博客日均幾百 UV 的流量 SQLite 完全無壓力。個人博客的寫入頻率極低主要是你自己發(fā)文讀多寫少SQLite 的瓶頸遠未到。Flask 默認并發(fā)模型在處理這種輕量訪問時一次性讀取幾張表基本沒有壓力。等到真有一天流量大到 SQLite 撐不住時再把 SQLALCHEMY_DATABASE_URI 改成 mysqlpymysql:// 用戶:密碼host/dbname模型代碼一行都不用動。所以選 SQLite 做起步是正確的默認選擇。不過有一點要提醒SQLite 不支持并發(fā)寫入多個進程同時寫庫可能觸發(fā) database is locked。我的規(guī)避方式是部署時用單進程跑 Flask或者把寫操作放在同一進程的請求里避免外部腳本和 Web 進程同時寫庫。4. 把路由和模板串起來從「顯示一條假數據」到「讀數據庫渲染真實文章」4.1 核心路由怎么設計才不需要到處改 URL做博客的路由表面上就是首頁列表、文章詳情、發(fā)布新文章這幾條。但這里有個細節(jié)值得一開始就定好——用 slug 還是 id 作為文章詳情的主鍵。我推薦 slug因為它在 URL 里可讀對搜索和分享都友好。Slug 的生成規(guī)則通常是中文標題轉拼音或直接允許英文短橫線。這里有個坑兩個文章 slug 不能重復得像下面這樣處理沖突。# app/views.py from flask import Blueprint, render_template, request, redirect, url_for, abort from .models import Post from . import db bp Blueprint(main, __name__) def slugify(text: str) - str: # 簡單實現截斷、去空格、轉小寫、不允許特殊字符 allowed set(abcdefghijklmnopqrstuvwxyz0123456789-) slug -.join(text.strip().lower().split()) out [] for ch in slug: if ch in allowed or ch -: out.append(ch) return -.join(.join(out).split(-))[:60]上面的 slugify 只處理英文和數字。中文標題怎么辦常見做法是在表單里增加一個「URL 別名」輸入框由博主自己填拼音或英文短詞。自動轉拼音需要引入額外依賴對「簡單博客」來說價值不大手動填反而更可控。4.2 首頁列表與文章詳情分頁參數值得花兩分鐘調好首頁展示的是所有文章按時間倒序數量控制在每頁 58 條比較舒服。Jinja2 模板里渲染分頁導航是幾乎所有博客通用的做法而 Flask 的paginate方法正好幫我們省掉了手寫 offset 的麻煩。bp.route(/) def index(): page request.args.get(page, 1, typeint) pagination Post.query.order_by(Post.created_at.desc()).paginate(pagepage, per_page5, error_outFalse) posts pagination.items return render_template(index.html, postsposts, paginationpagination)參數說明per_page5表示每頁 5 篇error_outFalse表示頁碼越界時返回空列表而不是 404。前端在 base.html 里加一段分頁判斷當pagination.has_prev或has_next時顯示上一頁/下一頁鏈接。這里我還習慣在首頁順手帶Post.query.filter_by(categorycategory)的分類篩選以后加菜單不必再動路由。文章詳情路由的核心參數校驗一定要做好bp.route(/post/string:slug) def post_detail(slug): post Post.query.filter_by(slugslug).first_or_404() return render_template(post.html, postpost)first_or_404()是 Flask-SQLAlchemy 給我們的福利它讓文章不存在時自動拋 404省去了手動abort。注意這里我特意用filter_by(slugslug)而不是get_by_id就是強調了 slug 的唯一性價值。4.3 后臺發(fā)布頁提交表單時做好校驗別讓 Markdown 語法把頁面搞崩發(fā)布文章是博客的核心操作。簡單博客可以不需要單獨的后臺管理系統(tǒng)直接在后臺路由里放一個表單頁就夠了。bp.route(/admin/new, methods[GET, POST]) def new_post(): if request.method POST: title request.form.get(title, ).strip() slug request.form.get(slug, ).strip() content request.form.get(content, ).strip() category request.form.get(category, 默認).strip() excerpt request.form.get(excerpt, content[:80]).strip() if not title or not content: return render_template(editor.html, error標題和正文不能為空, titletitle, slugslug) if not slug: slug slugify(title) # 檢查 slug 是否重復 if Post.query.filter_by(slugslug).first(): return render_template(editor.html, errorURL 別名已存在請換一個, titletitle, contentcontent) post Post(titletitle, slugslug, contentcontent, categorycategory, excerptexcerpt) db.session.add(post) db.session.commit() return redirect(url_for(main.post_detail, slugslug)) return render_template(editor.html, postNone)這段我在團隊里總是反復強調的點是校驗放在模板之外。有人靠模板里的 hidden 字段防止重復提交但爬蟲可以繞過還有人直接在視圖里寫 if 判斷但不返回錯誤信息用戶不知道哪里沒填。我的習慣是校驗失敗時把已填寫的內容回顯并且附帶具體錯誤提示這樣用戶改一次就能過。editor.html 模板不復雜一個標題輸入框一個 slug 輸入框一個正文 textarea再來一個分類輸入框。textarea 里塞 content 時要用{{ post.content if post else }}而不是直接寫死這樣出錯回顯時才不會丟稿。在建表后的首次使用時還有一個我必然會補的邏輯創(chuàng)建文章后立刻跳轉到詳情頁這樣你能第一時間確認 Markdown 渲染是否正確避免「保存成功了但頁面是空白」的尷尬。5. Markdown 渲染與界面細節(jié)讓文章真正「看得下去」5.1 為什么博客內容必須用 Markdown純文本和富文本各有各的坑個人博客本質上是個寫作工具寫作體驗直接決定你堅持得下去還是三分鐘熱度。純文本框是夠簡單但標題、列表、代碼塊全靠肉眼分辨長文章會非常痛苦。富文本編輯器粘貼時經常帶上一堆亂七八糟的內聯樣式最后頁面風格徹底崩盤。Markdown 的好處是純文本可備份、可 diff渲染結果穩(wěn)定還不受編輯器平臺綁架。我在本地寫完直接粘到 textarea甚至用腳本批量導入歷史文章都是順暢的。就個人博客而言Markdown 是當前最穩(wěn)的選擇。后端渲染時我這里使用markdown庫# app/views.py 里加一個模板過濾器 import markdown as md bp.app_template_filter(markdown) def markdown_filter(text: str): return md.markdown( text, extensions[extra, fenced_code, tables, codehilite, nl2br], output_formathtml5 )參數說明extra包含刪除線、腳注、定義列表等常用擴展fenced_code讓三引號代碼塊解析tables支持 GitHub 風格表格codehilite配合 CSS 高亮。模板里使用如下div classpost-content {{ post.content | markdown | safe }} /divsafe是個雙刃劍。markdown 庫默認會把原始 HTML 按不安全輸入輸出如果你文章由管理員自己寫、沒有開放評論問題不大如果以后接入了用戶生成內容這個safe必須去掉或者用bleach庫過濾掉 script 標簽再做白名單否則就是 XSS 漏洞入口。先記住這一個結論個人博客自己寫自己看safe 沒問題一旦開放多人編輯馬上撤掉。5.2 閱讀體驗的細節(jié)正文寬度、代碼塊、目錄跳轉Flask 的模板繼承讓統(tǒng)一的閱讀樣式變得簡單。base.html 里放導航和容器post.html 里只要寫內容區(qū)域即可。正文寬度我一般控制在 760px 左右max-width: 760px; margin: 0 auto; padding: 20px;這個寬度對中文閱讀是最舒服的。太寬會讀串行太窄換行頻繁。代碼塊要有背景色和橫向滾動中文正文和代碼塊之間加一點 margin否則連在一起視覺上是災難。另外值得做的一個小功能是給 Markdown 渲染后的標題自動生成錨點然后模板里加一個「目錄」抽屜。extra擴展默認會給 h2/h3 生成 id 嗎不會需要開啟toc擴展。如果不想碰擴展的細節(jié)可以在 markdown 里給extra追加tocmd.markdown(text, extensions[extra, fenced_code, tables, codehilite, toc])加了 toc 擴展后渲染出來的[TOC]占位符會自動變成目錄列表。這個功能對長文章的價值是立竿見影的讀者能快速跳到目標章節(jié)。不要覺得這是錦上添花真實寫作到了第 15 篇文章以后你就能體會到目錄對體驗的影響有多大。5.3 時間顯示與本地時區(qū)轉換的小細節(jié)SQLite 里存的datetime.utcnow保存的是零時區(qū)時間。直接顯示在頁面上國內用戶看到的會比本地時間晚 8 小時這是一個很影響觀感的細節(jié)。處理方案是在模板過濾器里做轉換from datetime import timezone, timedelta bp.app_template_filter(localtime) def localtime_filter(dt): if dt is None: return local dt.replace(tzinfotimezone.utc).astimezone(timezone(timedelta(hours8))) return local.strftime(%Y-%m-%d %H:%M)上面把 utc 轉為東八區(qū)時間這段代碼僅適合固定在國內時區(qū)的博客。如果部署的服務器區(qū)域不確定更穩(wěn)妥的方案是讓瀏覽器端用 JavaScript 通過 getTimezoneOffset 做轉換把時間格式還給前端掌控。我自己傾向用 UTC 存儲、前端展示時轉換這樣代碼放到任何區(qū)域的機器上都不會因為環(huán)境差異導致時間錯亂。6. 避坑指南Flask 博客遇到的 5 個高頻翻車現場與排查路徑6.1 模板繼承導致 CSS 找不到頁面「裸奔」現象首頁能顯示純文本內容但沒有樣式瀏覽器控制臺顯示 static/style.css 404。原因Jinja2 模板里寫了link relstylesheet href/static/bootstrap.css但 Flask 的靜態(tài)文件默認掛載在/static/并且文件必須位于 app/static 下。如果你把模板放在項目根目錄的 templates 而靜態(tài)目錄忘記放在正確位置URL 會 404。解決確認文件結構為 app/static/style.css模板用url_for(static, filenamestyle.css)生成路徑。一定不要硬編碼 /static/ 前綴因為在部署到子路徑時硬編碼會再次失效。6.2 slug 重復導致數據庫無法寫入唯一索引現象發(fā)布第二篇標題一樣的文章表單提交后報了IntegrityError重定向丟失。原因slug 字段有 uniqueTrue但你在視圖里沒有做重復檢查或者檢查邏輯放在了db.session.commit()之后。SQLite 的完整約束在 commit 時才觸發(fā)檢查所以只在內存里查是一次假成功。解決在 commit 前先Post.query.filter_by(slugform_slug).first()判斷存在則提示修改。如果線上環(huán)境已有臟數據導致索引建立失敗先刪掉重復數據再重建索引。這一點在本地跑通后也要同步給團隊否則協(xié)作時同樣會踩到。6.3 代碼塊不換行頁面整體被撐破現象Markdown 里粘貼一段含超長 URL 或 JSON 的代碼塊渲染出來整個頁面橫向滾動條出現布局亂套。原因默認 HTML 的 pre 元素不會自動換行長字符串會把容器寬度撐破。解決在 CSS 里對 pre 或 code 增加pre { overflow-x: auto; white-space: pre; word-break: normal; }這里的overflow-x: auto讓代碼塊內可橫向滾動white-space: pre保留縮進與空格。要留心的是不要用pre-wrap它會破壞代碼縮進。我習慣在開發(fā)預覽時黏貼一次長行代碼強制驗證這條規(guī)則。6.4 表單重復提交導致數據庫出現一模一樣的空文章現象提交文章時網絡較慢用戶連續(xù)點了兩次按鈕出現兩條內容完全相同的記錄。原因沒有做重復檢測也沒用重定向刷新模式。提交成功后的 POST 響應如果直接返回模板而不是redirect瀏覽器刷新時會重發(fā) POST 請求。解決提交成功統(tǒng)一走redirect(url_for(...))這是 Post/Redirect/Get 模式的精髓。配合 slug 唯一約束做兜底后基本杜絕了這個坑。如果你未來接入編輯器自動保存還需要在接口層用請求時間戳做防抖。6.5 遷移到云服務器后少量訪問 500 錯誤日志卻看不到 traceback現象本地開發(fā)時一切正常部署到服務器偶爾 500日志里只有一行「Internal Server Error」沒有具體堆棧。原因Flask 默認只在調試模式打印全量 traceback生產模式下 debugFalse 后錯誤被吞掉沒有登記到日志。解決設置app.config[PROPAGATE_EXCEPTIONS]或者加一個 errorhandler 把異常記錄到文件import logging if not app.debug: stream_handler logging.StreamHandler() app.logger.addHandler(stream_handler) app.logger.setLevel(logging.WARNING)上面這段加在 create_app 末尾即可。排查時看到日志里出現 ValueError、KeyError 的概率很高最典型是模板里訪問了一個 form 變量但視圖某次沒有傳遞沒有日志這些幾乎不可能定位到原因。這個追加日志的習慣我第一次在部署環(huán)境里就返回了巨大的復用價值否則半夜被報警找半天都不知道錯在哪。7. 部署與后續(xù)優(yōu)化從本地跑通到可持續(xù)寫作值得補的幾個小技巧如果你只是本地寫著玩跑python manage.py runserver就夠了。但如果認真對待這個博客部署后有幾個點我強烈建議補上第一在 nginx 或 Caddy 后面用 gunicorn 啟動讓它用多 worker 模式運行第二把 session 密鑰從代碼里抽到環(huán)境變量避免密鑰泄露導致會話偽造問題第三寫一個簡單的備份腳本把 instance/blog.db 定時打包到云存儲或本地磁盤。數據庫文件本身不過幾十 KB每天備份一次的成本幾乎為零但能避免「服務器到期數據全部蒸發(fā)」的慘劇。我個人遇到過因為忽略備份導致全部文章丟失的翻車現場那是唯一一次讓我認識到個人博客的核心資產是內容不是代碼。部署時還有一個值得做的功能是給文章加閱讀計數。有人覺得要引入 Redis 或加個計數表其實用 SQLite 就能做到。在 Post 模型里加一個views整數列詳情頁渲染時post.views 1并提交。不過要注意每次刷新都會累加要防止刷流量。簡單方案是在前端用 sessionStorage 記錄當前用戶會話里是否訪問過該文章后端只接收入參來更新。這樣每日幾十 UV 的訪問量下完全夠用不會過度設計。最后一個常用技巧是把「摘要」自動生成改為手動控制并且讓摘要支持 Markdown 語法。編輯頁里加一個「摘要」輸入框未填時自動從正文前 100 字截斷。這樣列表頁可以有漂亮的摘要而不是一篇篇全文字段的堆砌。未來想加 RSS 輸出只需在 routes 里加一個響應 XML 的視圖想做站內搜索用LIKE %keyword%查詢足以應對幾百篇文章的體量不必上全文索引。我的習慣是每一步都小步走一個新功能能在一小時內完成并驗證就堅決不憋大招。按這個節(jié)奏博客才會越用越順手而不是變成一個處處要維護、越來越不想碰的「半成品項目」。最后想再提醒一句部署前至少把 gunicorn、SQLite 權限、靜態(tài)文件緩存這三個點過一遍這三個地方往往是新手走在本地正常、上線翻車的重災區(qū)。把備份腳本做好文章寫完就順手提交一次哪怕哪天服務器出問題你仍能快速把全部數據恢復起來繼續(xù)寫。希望幫到你。本文還有配套的精品資源點擊獲取