简介一份以Flask框架搭建的小型个人博客项目面向Python基础学习者与Web后端入门者适合作为CMS内容管理的起步示例。项目完整展示了应用初始化、数据库建模、路由分发、模板渲染、用户登录认证等关键环节并按app与run.py组织目录代码分层清晰便于在本地快速跑通并继续改造。资源包共19个文件以12个html模板、2个py文件为主另含css、js静态资源、依赖说明与README压缩包仅71KB。templates目录提供基础页面框架py文件承担入口与业务视图静态文件支撑界面样式整体轻量精简下载后即可对照学习。已有5267人浏览学习适合用少量时间走通Flask开发全链路。通过该包可以掌握从创建Flask实例、定义数据模型、配置路由视图到博客页面渲染与调试启动的完整流程并在此基础上扩展评论、分类、搜索等功能逐步完善个人博客系统。1. 用 Flask 写个人博客是最容易放弃也最容易成功的 Python 项目学 Python 的人十有八九动过“自己搭个博客”的念头但大多数死在同一个地方技术选型太重。用 Django 觉得框架替你做了太多事光是 admin 后台和 ORM 的迁移就能耗掉一个周末用 WordPress 又觉得跟 Python 没什么关系折腾半天还是在写 PHP。Flask 是那条中间路线——它只给你请求路由和模板渲染两块最核心的地基文章存储、翻页逻辑、表单校验、防止脚本注入全都要你自己一行行写出来。这份“自己动手”的代价恰恰是它最大的价值你的第一份代码可能只有二十行但你已经跑通了一个从浏览器请求到 Python 处理再到 HTML 响应的完整闭环迭代到第四五个晚上你能把评论、标签、归档页都加上对 Web 应用的理解远超任何教程给你的印象。这篇笔记会把从空目录到一个能上线、能写文章、能防住基本攻击的 Flask 博客的完整路径拆开讲适合刚学完 Python 语法、想找个真实项目练手的人也适合写过脚本但没碰过 Web 框架的人。顺便说一句整个过程不需要 Docker不需要前端框架一台能跑 Python 的电脑就够。2. 先把最小骨架立起来路由、模板与第一个页面2.1 为什么 Flask 适合这个项目而不是别的框架Flask 的核心设计是“微内核”它默认不带数据库抽象层、不带表单库、不带用户认证但恰恰是这些“缺失”让博客项目变得可教、可拆、可扩展。你每引入一个扩展Flask-SQLAlchemy、Flask-WTF、Flask-Login就多理解一层 Web 框架的通用设计而 Django 把一切都打包好新手反而搞不清请求是怎么进来、又是怎么出去的。用 Flask 写博客你实际上在用最少的黑匣子完成一套完整的 Web 应用这对后续转 Django 或 FastAPI 都有帮助。另一个务实的理由是调试成本。Flask 开发服务器支持代码改动后自动重载出错时浏览器页面直接显示堆栈跟踪这对调试模板语法错误特别有用。再加上 Python 生态里成熟的 SQLite、Jinja2 模板引擎几乎每个环节都有对应的最佳实践可循。把博客这种“增删改查 页面展示”的标准项目用它实现一遍能覆盖到路由设计、HTTP 方法、表单处理、数据库操作、前端模板继承这五个核心知识点性价比在 Python 项目中算是非常高的一档。2.2 搭建项目文件和最小应用我习惯先建一个干净的目录结构不急着分包先把单文件跑通再逐步拆。下面的命令创建项目根目录和基本文件mkdir my_blog cd my_blog python3 -m venv venv source venv/bin/activate pip install flask flask-sqlalchemy flask-wtf这三条命令分别做了三件事创建隔离的 Python 环境避免污染全局环境、激活虚拟环境、一次性装好后面要用的三个库。如果安装慢可以加-i https://pypi.tuna.tsinghua.edu.cn/simple指定镜像源。然后写最简应用app.pyfrom flask import Flask, render_template app Flask(__name__) app.route(/) def index(): return render_template(index.html, title我的博客) if __name__ __main__: app.run(debugTrue)这里app Flask(__name__)创建了 Flask 应用实例__name__用于让 Flask 找到模板和静态文件的根目录app.route(/)把根路径绑定到index函数上render_template负责渲染templates目录下的index.html并把title变量传进去。debugTrue会在代码改动时自动重启服务同时把错误信息直接打到浏览器页面上开发阶段开着它很方便上线前记得关掉。在templates目录下建一个base.html作为所有页面的父模板!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title{% block title %}{% endblock %}/title link relstylesheet href{{ url_for(static, filenamestyle.css) }} /head body nav a href{{ url_for(index) }}首页/a /nav main {% block content %}{% endblock %} /main /body /html{% block %}是 Jinja2 模板继承的核心语法子模板通过重写 block 来填充内容公共部分如导航栏和 CSS 引用只需维护一次。这样后面每增加一个页面模板代码都不会重复。2.3 让首页展示文章列表从假数据到真查询先用假数据把页面效果跑起来再替换成数据库查询这样每一步都有可见的反馈。修改index视图app.route(/) def index(): posts [ {id: 1, title: 第一篇博客, created_at: 2024-01-01}, {id: 2, title: Flask 学习笔记, created_at: 2024-01-02}, ] return render_template(index.html, postsposts)对应的index.html{% extends base.html %} {% block title %}首页{% endblock %} {% block content %} h1最新文章/h1 ul {% for post in posts %} li a href#{{ post.title }}/a span{{ post.created_at }}/span /li {% endfor %} /ul {% endblock %}这一段跑通之后你的 Flask 博客就有了第一个真正的页面路由接收请求、视图函数准备数据、模板渲染 HTML 返回给浏览器。后面所有的功能都是在这条链路上增加细节。3. 数据层与文章写作SQLAlchemy 模型和完整的增删改查3.1 为什么用 SQLite SQLAlchemy 而不是直接写 SQL博客的典型数据量是几百篇文章、几千条评论SQLite 单文件数据库完全能扛住而且部署时不需要单独装数据库服务备份就是把一个.db文件拷走。我见过不少人为了“以后扩展”一上来就配 MySQL结果折腾半天连接配置文章一个字还没写——这种过度设计是这个项目最常见的翻车点。ORM 层选 SQLAlchemy 不是因为它性能好而是因为它把最枯燥的建表、插入、查询封装成了 Python 对象操作同时保留手写 SQL 的逃生通道。Flask-SQLAlchemy 作为官方推荐的扩展把数据库会话、模型基类、迁移工具都绑定到了 Flask 应用上配置成本比裸用 SQLAlchemy 低一个量级。这里不需要上 Flask-Migrate因为博客的模型结构变化不频繁直接db.create_all()就够了。3.2 定义 Post 模型和数据库初始化from flask_sqlalchemy import SQLAlchemy from datetime import datetime db SQLAlchemy() class Post(db.Model): __tablename__ posts id db.Column(db.Integer, primary_keyTrue) title db.Column(db.String(120), nullableFalse) content db.Column(db.Text, nullableFalse) created_at db.Column(db.DateTime, defaultdatetime.utcnow) updated_at db.Column(db.DateTime, defaultdatetime.utcnow, onupdatedatetime.utcnow)模型定义里三个值得注意的点id主键用自增整数就够了不需要 UUIDtitle限长 120 是因为博客标题不会更长同时给数据库一个合理的长度约束content用Text类型存长文。defaultdatetime.utcnow用函数而不是函数调用结果这样才能在每次插入时生成当前时间而不是在导入时固定一个时间。在app.py里完成应用与模型的绑定app.config[SQLALCHEMY_DATABASE_URI] sqlite:///blog.db app.config[SQLALCHEMY_TRACK_MODIFICATIONS] False db.init_app(app) with app.app_context(): db.create_all()sqlite:///blog.db表示数据库文件放在项目根目录下TRACK_MODIFICATIONS设为 False 是为了关闭 ORM 的每次改动追踪省掉一堆内存开销和告警日志。db.create_all()必须在应用上下文中执行因为 SQLAlchemy 需要知道当前绑定的是哪个应用。3.3 实现文章发布的完整 CRUD新增、列表、详情、编辑、删除CRUD 是博客的核心每个操作对应一个路由。先写新增文章的视图和模板from flask import request, redirect, url_for, flash app.route(/posts/new, methods[GET, POST]) def create_post(): if request.method POST: title request.form.get(title, ).strip() content request.form.get(content, ).strip() if not title or not content: flash(标题和内容不能为空) return render_template(edit_post.html, postNone) post Post(titletitle, contentcontent) db.session.add(post) db.session.commit() return redirect(url_for(view_post, post_idpost.id)) return render_template(edit_post.html, postNone)这段代码的关键点在于methods[GET, POST]让同一个 URL 同时承担表单展示和表单提交两种职责request.form拿到的是用户 POST 上来的表单数据空值校验放在业务层而不是模板层因为模板没法阻止程序逻辑直接构造非法请求flash用于在下一个请求中显示一次性提示消息。把文章写进数据库的核心就两行db.session.add(post)和db.session.commit()前者把对象加入会话后者把变更持久化到数据库文件。详情页与编辑删除对应的视图函数app.route(/posts/int:post_id) def view_post(post_id): post db.session.get(Post, post_id) if post is None: abort(404) return render_template(view_post.html, postpost) app.route(/posts/int:post_id/edit, methods[GET, POST]) def edit_post(post_id): post db.session.get(Post, post_id) if post is None: abort(404) if request.method POST: post.title request.form.get(title, ).strip() post.content request.form.get(content, ).strip() db.session.commit() return redirect(url_for(view_post, post_idpost.id)) return render_template(edit_post.html, postpost) app.route(/posts/int:post_id/delete, methods[POST]) def delete_post(post_id): post db.session.get(Post, post_id) if post: db.session.delete(post) db.session.commit() return redirect(url_for(index))这里要用int:post_id而不是post_id因为类型转换器会把 URL 参数强制变成整数如果用户访问/posts/abc会返回 404而不是让 Python 抛ValueError导致 500。db.session.get(Post, post_id)是 SQLAlchemy 2.0 推荐的按主键查询方式比Post.query.get(post_id)更清晰。删除操作必须用 POST 方法而不是 GET这样搜索引擎爬虫不会通过预取链接把文章删掉也能避免用户误触一个a href就删掉整篇文章。编辑页把post对象作为post变量传给模板模板里读取post.title作为表单的默认值这是一个非常常见但新手容易漏掉的细节。3.4 表单模板的写法与 CSRF 保护模板部分用同一个edit_post.html同时承担新增和编辑的渲染靠是否传入post对象来区分{% extends base.html %} {% block content %} h1{% if post %}编辑文章{% else %}写新文章{% endif %}/h1 form methodpost {{ form.hidden_tag() }} p label fortitle标题/label input typetext idtitle nametitle value{{ post.title if post else }} /p p label forcontent内容/label textarea idcontent namecontent rows12{{ post.content if post else }}/textarea /p button typesubmit保存/button /form {% endblock %}这里我直接用 Flask-WTF 的form.hidden_tag()来输出 CSRF 令牌字段如果不用 Flask-WTF就得在模板里手动写input typehidden namecsrf_token value{{ csrf_token() }}然后在视图函数里手动校验。用 Flask-WTF 的好处是把校验和渲染统一了代价是多引入一个扩展但它的安全价值非常明确——没有这个令牌第三方网站可以构造一个表单 POST 到你的博客删除接口利用用户浏览器中的会话完成一次跨站请求伪造攻击。对应的视图函数加入 CSRF 校验用 Flask-WTF 的全局保护from flask_wtf.csrf import CSRFProtect csrf CSRFProtect(app)这行代码放在应用配置之后即可它会自动拦截所有 POST 请求检查表单里的csrf_token字段。因为我们的模板已经用了hidden_tag()所以前端不需要额外改动。4. 用 Pagination 给博客加分页从全部文章到可读的列表4.1 博客翻页的需求边界数据量大时才需要博客文章超过四五十篇之后再好的页面也经不起全部渲染。常见的翻页方案有两种一种是只显示“上一页/下一页”的简单分页另一种是带页码数字的完整分页。简单分页实现成本低、逻辑清晰适合文章量不大或追求极简风格的博主完整分页多一个页码列表用户体验稍好但代码复杂度增加。我的建议是先用简单分页——因为博客本身是练手项目等文章积累到一百篇再升级也不迟分页的数据库查询逻辑是一样的。Flask-SQLAlchemy 的paginate()方法把“查询总数、计算偏移量、截取当前页数据”这三件事封装好了不需要手动写LIMIT和OFFSET。它返回一个Pagination对象里面带items当前页的数据、page页码、pages总页数、has_prev/has_next是否有前一页/后一页等属性模板层直接用这些属性渲染翻页控件。4.2 给首页加上分页视图调整与模板实现修改首页视图按时间倒序并分页app.route(/) app.route(/page/int:page_num) def index(page_num1): pagination Post.query.order_by(Post.created_at.desc()).paginate( pagepage_num, per_page5, error_outFalse ) posts pagination.items return render_template(index.html, postsposts, paginationpagination)order_by(Post.created_at.desc())让新文章排在最前per_page5是每页文章数这个值我一般在实际项目中根据自己写文章的频率调整一个月写两三篇的话每页五篇完全够用error_outFalse很关键用户手动访问不存在的页码时不会报 404而是返回空列表的最后一页。模板里在文章列表下方加翻页控件{% if pagination.has_prev %} a href{{ url_for(index, page_numpagination.prev_num) }}上一页/a {% endif %} span第 {{ pagination.page }} / {{ pagination.pages }} 页/span {% if pagination.has_next %} a href{{ url_for(index, page_numpagination.next_num) }}下一页/a {% endif %}这里has_prev和has_next是布尔值用来避免第一页出现“上一页”链接、最后一页出现“下一页”链接。url_for生成链接时需要把page_num作为查询参数传进去Flask 会自动拼成/page/2或/?page_num2的形式。4.3 分页的排序与参数调优几篇文章一页最合适分页参数的选择直接影响阅读体验。太密每页两篇用户要不停点击太疏每页二十篇页面加载慢且失去分页意义。我的经验是纯文字博客每页 58 篇带大图的每页 35 篇。至于per_page要不要做成可配置的看个人需求——想做成“每页 10、20、50 篇可选”也很简单加一个前端下拉框点击后跳转到带?per_page10参数的 URL 即可。翻页时还要注意一个常见的顺序陷阱任何时候都用created_at排序不要用id因为如果以后做“文章置顶”功能用id排序会直接废掉置顶逻辑。另外删除某篇文章后页码索引会自动前移用户正在看的第 10 页可能会因此变成第 9 页的内容这是分页的天然特性不用额外处理。5. 把评论和标签加上去两个实用的模型设计方案5.1 评论模型不要让博客变成单向输出一个没有评论功能的博客更像一个公告栏。写评论功能之前先想清楚需求是否需要匿名评论是否需要管理员回复是否需要邮件通知入门方案建议只做“姓名 正文”的匿名评论不做登录系统——这能大幅降低复杂度同时足以覆盖个人博客 90% 的交流诉求。评论模型的设计核心是外键关联class Comment(db.Model): __tablename__ comments id db.Column(db.Integer, primary_keyTrue) author db.Column(db.String(80), nullableFalse) content db.Column(db.Text, nullableFalse) created_at db.Column(db.DateTime, defaultdatetime.utcnow) post_id db.Column(db.Integer, db.ForeignKey(posts.id), nullableFalse) post db.relationship(Post, backrefdb.backref(comments, lazyTrue))db.ForeignKey(posts.id)在数据库层面建立约束确保post_id必须指向已存在的文章db.relationship则在 ORM 层建立关联通过post.comments即可获得该文章下所有评论。这里容易踩的一个坑是lazyTrue表示访问post.comments时才查询数据库如果用lazydynamic返回值会从列表变成一个查询对象导致模板里for comment in post.comments的行为完全不一样。对评论这种数量不大、需要在页面一次性全部显示的场景lazyTrue是对的。在文章详情页模板中显示评论和提交表单h3评论{{ post.comments | length }}/h3 {% for comment in post.comments %} div classcomment strong{{ comment.author }}/strong span{{ comment.created_at.strftime(%Y-%m-%d) }}/span p{{ comment.content }}/p /div {% endfor %} h4发表评论/h4 form methodpost action{{ url_for(add_comment, post_idpost.id) }} {{ form.hidden_tag() }} input typetext nameauthor placeholder你的名字 required textarea namecontent rows4 placeholder说点什么… required/textarea button typesubmit提交/button /formcreated_at.strftime(%Y-%m-%d)用来格式化时间显示因为数据库里存的是datetime对象直接输出会带时分秒。控制评论长度的校验也应该在视图函数里做同时设置maxlength属性前后端双重校验是可靠的实践。5.2 标签模型多对多关系是入门必过的坎标签和文章是多对多关系——一篇文章可以有多个标签一个标签可以对应多篇文章。在关系型数据库里实现多对多需要一个中间表tag_post db.Table(tag_post, db.Column(post_id, db.Integer, db.ForeignKey(posts.id), primary_keyTrue), db.Column(tag_id, db.Integer, db.ForeignKey(tags.id), primary_keyTrue) ) class Tag(db.Model): __tablename__ tags id db.Column(db.Integer, primary_keyTrue) name db.Column(db.String(30), uniqueTrue, nullableFalse) posts db.relationship(Post, secondarytag_post, backrefdb.backref(tags, lazyTrue))db.Table定义了一个纯表结构不需要额外的模型类secondarytag_post告诉 SQLAlchemy 通过这个中间表来建立关联。给文章打标签的操作是post.tags.append(tag)保存时只需要提交post对象SQLAlchemy 会自动处理中间表的写入。这里容易踩的坑是标签重名给文章添加标签时应该先查有没有同名标签有就直接用现成的没有才创建新的否则数据库里会出现两个“Python”标签。5.3 按标签筛选文章路由加条件查询标签页本质是“按关联过滤后的文章列表”app.route(/tag/string:tag_name) def tag_posts(tag_name): tag Tag.query.filter_by(nametag_name).first_or_404() posts tag.posts return render_template(index.html, postsposts, paginationNone, tag_nametag.tag_name)这里直接复用index.html作为列表模板因为文章列表的渲染逻辑完全一致。filter_by(nametag_name).first_or_404()是最省事的写法找到标签就继续找不到直接返回 404 页面。注意tag.posts返回的是列表而不是分页对象如果某个标签下文章特别多需要在这里也做分页做法和前面的paginate完全相同区别只是查询条件换成按标签过滤。6. 部署与踩坑从本地跑到公网的最后一公里6.1 踩坑记录三个能让新手当场崩溃的问题第一个坑运行python app.py后浏览器打不开页面显示“连接被拒绝”。原因通常是 Flask 开发服务器默认只监听127.0.0.1也就是只能本机访问。解决办法是启动时指定host0.0.0.0但要注意这会暴露到整个局域网调试时开着它要小心。第二个坑修改了模型结构比如给Post加了一个字段但重启应用后报sqlite3.OperationalError: no such column。原因是用db.create_all()不会修改已存在的表结构需要手动删除blog.db文件后重新创建或者引入 Flask-Migrate 做迁移。第三个坑部署到公网后文章内容里的 HTML 标签直接显示在页面上或者用户在评论里写script就被执行了。原因是 Jinja2 默认对变量输出做了转义但你可能在模板里用| safe过滤器或直接把request.form的值传回了页面评论必须做净化处理最简单的做法是只渲染纯文本。6.2 生产环境部署用 gunicorn 替换开发服务器app.run()是开发服务器的启动方式它的性能不足以支撑公网访问部署时必须换成 WSGI 服务器。一个典型的部署方案是 Nginx 反向代理 Gunicornpip install gunicorn gunicorn -w 4 -b 127.0.0.1:8000 app:app-w 4表示启动 4 个工作进程app:app表示导入app.py中的名为app的应用对象。Gunicorn 启动后监听本机的8000端口让 Nginx 把公网请求转发到这个端口。配置文件如下server { listen 80; server_name your_domain.com; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }proxy_pass是转发指令proxy_set_header X-Real-IP用于把用户的真实 IP 传给 Flask否则request.remote_addr拿到的一律是127.0.0.1。这一步如果你没有云服务器在本地用虚拟机或树莓派练手效果一样核心流程都是“反向代理转发给 GunicornGunicorn 加载 Flask 应用”。6.3 安全必做清单密码存储、SQL 注入、XSS这个项目虽然不带用户系统但安全防线不能省。如果以后要加管理员登录密码存储绝不可以用 SHA 或 MD5 明文哈希至少用 Werkzeug 自带的generate_password_hashfrom werkzeug.security import generate_password_hash, check_password_hash hashed generate_password_hash(your_password) check_password_hash(hashed, your_password) # 返回 TrueSQL 注入方面SQLAlchemy 的 ORM 已经做了参数化查询只要不手拼 SQL 字符串这个项目基本没有注入面。唯一要注意的是text()原生态查询语句的使用场景如果在搜索功能里用了LIKE不要用字符串拼接而要用:keyword绑定参数from sqlalchemy import text result db.session.execute( text(SELECT * FROM posts WHERE title LIKE :kw), {kw: f%{keyword}%} )XSS 方面Jinja2 对{{ post.content }}默认转义为纯文本但如果以后给文章内容加了 Markdown 渲染库一定要注意输出前过滤掉script标签。我见过不少 Markdown 库默认允许原生 HTML结果文章评论区成了跨站脚本的后花园。博客项目上线后最好每篇文章打开浏览器开发者工具看一下凡是自己写的内容渲染后出现奇怪的按钮或弹窗八成就是有标签没被过滤掉。7. 让博客更像一个产品阅读量统计与按时间归档博客从“能跑”到“好用”最值得加的两个功能是阅读量统计和按月份归档。阅读量能让你知道哪些文章值得持续维护归档功能则让长尾内容更容易被翻出来。阅读量统计用 Cookies 去重是入门方案里性价比最高的——不用建表、也不需要登录逻辑是用户第一次访问详情页时在 Cookie 里记录一个已读文章 ID 的列表若当前文章 ID 在列表里则不计入否则浏览量加一并把 ID 写回 Cookie。具体实现时给Post模型加一个views字段views db.Column(db.Integer, default0) app.route(/posts/int:post_id) def view_post(post_id): post db.session.get(Post, post_id) if post is None: abort(404) visited request.cookies.get(visited_posts, ) if str(post_id) not in visited.split(,): post.views 1 db.session.commit() visited_posts visited f,{post_id} if visited else str(post_id) else: visited_posts visited response make_response(render_template(view_post.html, postpost)) response.set_cookie(visited_posts, visited_posts, max_age86400*30) return responsemake_response用来构造响应对象这样才能在渲染页面之后额外追加Set-Cookie头max_age让 Cookie 存活 30 天避免用户每次刷新都认为是新访问。这个方案的统计精度有限——用户清 Cookie 或换浏览器后同一个 IP 会重复计数但它已经能反映文章相对热度足够支撑“哪篇文章值得写续篇”这种判断。按月份归档的实现也不复杂from sqlalchemy import func app.route(/archive) def archive(): archives db.session.query( func.strftime(%Y-%m, Post.created_at).label(month), func.count(Post.id).label(count) ).group_by(month).order_by(month).all() posts_by_month {} for month, count in archives: posts_by_month[month] Post.query.filter( func.strftime(%Y-%m, Post.created_at) month ).all() return render_template(archive.html, posts_by_monthposts_by_month)func.strftime是 SQLite 的日期格式化函数在 MySQL 和 PostgreSQL 上对应不同的写法如果你切换了数据库需要调整。归档页模板里分两层循环输出外层按月分组内层遍历该月的文章配合链接既可以按时间线展示历史文章也能看出自己写作频率的变化轨迹。这个项目做到这里最初那个不到三十行的app.py已经自然长成了一个有着模型、路由、模板、安全校验的完整 Web 应用。我自己的一个习惯是每次完成一个功能就用 Git 打一个标签比如v1.0-basic、v1.1-comments、v1.2-deploy。这样以后想回头对比“分页前的首页长什么样”或“哪个改动导致性能下降”时可以直接切换到对应节点。以后你回头看这个博客的代码会庆幸当时把每一步都拆得清清楚楚。如果你照着这篇笔记做完后给自己的博客加上第一条评论或迎来第一篇文章的点击那种满足感比跑通任何教程示例都强烈——希望这篇笔记能帮到你走到那一步。本文还有配套的精品资源点击获取
的优化思路)
