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