简介基于Python的小型博客系统毕业设计源码包面向计算机相关专业学生适合用于Web开发入门、毕设项目参考或实战练手。压缩包共18个文件包含3个Python脚本、4个HTML模板、3个Markdown文档、2个JSON配置及静态CSS与图片素材整体仅272KB结构精简。目前已有158人浏览学习。从内部结构看项目通过核心脚本与多个HTML模板页面相互配合覆盖博客文章发布/检索、友链管理等典型功能同时提供说明文档和Markdown测试文档便于对照学习轻量级Web框架下的路由设计、模板渲染与JSON数据交互等关键知识点。读者既可借此梳理博客系统的路由设计与数据流也能直接作为毕业设计源码做二次开发与扩展适用性较强。1. 拆开“基于Python的小型博客系统”文件与脚本的角色分配“博客系统”这四个字多数人第一反应是 Django 搭后台、MySQL 存数据。这份毕业设计源码完全没有框架依赖核心就四个 Python 脚本加一份 JSONindex.py 生成首页process.py 把 Markdown 文章切片成结构化数据friends.py 产出友链页search.html 做客户端检索。它把“数据库”降级成文件系统把“服务端渲染”降级成构建脚本用最小依赖把博客从写作到发布跑通。对要交课程设计的学生来说它能讲清楚数据流对写过 Flask/Django 的开发者来说它是“去框架化”的参考样本没有 ORM、没有路由表、没有 Session。下面按数据流向拆开说清每个脚本的边界末尾附上本地验证和增量构建的实操技巧。2. 数据管道process.py 把 Markdown 转成 passages.json 的完整逻辑2.1 front matter 解析与正文剥离这类静态博客工程的起点是 process.py。它的输入是 markdown 目录下的写作文件输出是根目录的 passages.json。选择 JSON 作为中间层而不是让 HTML 模板直接读 Markdown原因是 Python 原生的 Markdown 渲染依赖第三方包而 JSON 只用标准库的 json 模块就能解析index.py 生成首页、search.html 做搜索都要消费同一份数据JSON 把“解析”和“消费”两个阶段解耦替换其中任何一端都不影响另一端。front matter 是处理流程首先要解决的问题。常见做法是用---包裹的键值对声明元信息process.py 用正则把它从正文里剥离。下面的实现不依赖任何第三方库纯标准库可跑# process.py 中 front matter 解析的核心片段 import re from pathlib import Path def split_front_matter(text): 从 Markdown 文本中拆出元信息段与正文段。 返回 (meta_dict, body_text)。 pattern re.compile(r^---\s*\n(.*?)\n---\s*\n, re.S) m pattern.match(text) if not m: return {}, text meta {} for line in m.group(1).splitlines(): if : not in line: continue key, _, value line.partition(:) meta[key.strip()] value.strip() return meta, text[m.end():]这段代码有两个值得注意的参数细节。第一re.S标志让.可以匹配换行多行 front matter 才能被整体捕获去掉它遇到 title 跨行就会漏匹配。第二partition(:)比split(:)更安全——split 在值里带冒号时会切出多余元素partition 只切第一刀。答辩时如果被问到“为什么不用 split”这个差异就能说明你对比过字符串 API 的边界。2.2 字段设计、日期规范与摘要提取拆完 front matterprocess.py 还需要做三件事提取摘要、处理标签、规范化日期。常见字段设计如下字段类型来源消费方titlestrfront matter 的title缺省取正文第一个# 标题index.py、search.htmldatestrfront matter 的date统一为YYYY-MM-DDindex.py 排序summarystrfront matter 的summary缺省取正文前 120 字符首页卡片、搜索tagslist[str]逗号分隔后 stripsearch.html 标签层面过滤filestr源文件名不含扩展名详情页 href 拼接contentstr正文全文详情页渲染这里容易踩的坑是编码和空值。Windows 下用Path.read_text(encodingutf-8)读取时如果文件带 BOM第一个 key 会被写成\ufefftitle搜索和排序会全部失配。常见做法是读取后做一次key key.lstrip(\ufeff)的防御性清理。另一个坑是日期排序——JSON 里存回字符串比较时2024-1-5会排在2024-1-18前面因为逐位比较到第二个字符就分出高下了。处理方式是把日期补零到YYYY-MM-DD# process.py 排序前的日期规范化 from datetime import datetime def normalize_date(raw): 把 2024-1-5 / 2024/01/05 统一成 2024-01-05。 for fmt in (%Y-%m-%d, %Y/%m/%d, %Y.%m.%d): try: return datetime.strptime(raw, fmt).strftime(%Y-%m-%d) except ValueError: continue return raw posts.sort(keylambda p: p[date], reverseTrue)排序时reverseTrue把最新文章放在列表头部这是博客首页的常规信息架构。如果你希望“创建时间升序、修改时间置顶”可以给 JSON 额外维护updated字段排序 key 改成(p[updated] or p[date])但注意updated为空的文章会全部沉底写入前需要统一填充默认值。摘要生成如果 front matter 里没有显式声明不能直接从body[0:120]切因为 Markdown 开头往往是# 标题或图片引用截出来要么重复标题要么是一段形式的垃圾文本。常见做法是先剥离图片语法和标题符号再截取# 摘要提取前对正文做轻量清洗 plain re.sub(r!\[.*?\]\(.*?\), , body) # 去掉图片引用 plain re.sub(r^#{1,6}\s, , plain, flagsre.M) # 去掉 ATX 标题的 # 号 plain re.sub(r\[(.*?)\]\(.*?\), r\1, plain) # 链接只保留文字 summary plain.strip().replace(\n, )[:120]这组正则没有追求完整兼容 CommonMark但在课程设计和轻量工具场景下足够可靠。链接保留文字这一步尤其重要否则摘要里会残留完整的 URL搜索匹配时也会因为 URL 里的无关字符干扰结果。2.3 增量写入与幂等性process.py 每次运行都重新生成整个 passages.json 是最简单的但文章数量涨到几百篇后全量处理会变慢。基于文件 mtime 或内容哈希做增量判断是静态站点生成器里常见的优化路径import json, hashlib from pathlib import Path def needs_update(src, cache_file): 用文件内容的 SHA-1 判断是否需要重新解析。 cur hashlib.sha1(src.read_bytes()).hexdigest() cache json.loads( cache_file.read_text(encodingutf-8) ) if cache_file.exists() else {} return cache.get(src.name) ! curSHA-1 在这里只做变更检测不参与安全场景碰撞概率对个人博客完全可以接受。这个技巧的实际价值在于演示环节答辩时你反复修改某一篇 Markdown如果每次都全量重建等待时间会分散注意力做了增量判断后只重渲染变更文件节奏会顺很多。3. 渲染链路template.html 占位符与 index.py 的页面生成3.1 模板占位符与多页面复用拿到 passages.json 之后index.py 的工作是把数据填充进 template.html。先看模板侧的设计template.html 不是一份完整页面拷贝而是一段带占位符的骨架。常见做法是用$key形式的string.Template占位符这样不需要引入 Jinja2 依赖!-- template.html 中可复用的占位符骨架 -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title$page_title/title link relstylesheet hrefclassless.css /head body header nav a hrefindex.html首页/a a hrefsearch.html搜索/a a hreffriends.html友链/a /nav /header main $content /main footer p由 index.py 构建生成 · a href./passages.json数据源/a/p /footer /body /html占位符的含义如下占位符用途说明$page_title浏览器标签页标题首页填“小型博客系统”详情页填对应文章标题$content每页差异化的主体 HTML 字符串string.Template的safe_substitute在模板里出现缺失变量时不会抛异常而是原样保留字符串这比 f-string 做模板更稳——f-string 遇到文本里的花括号要么转义爆炸要么只能把模板拆成表达式可维护性差一截。3.2 首页列表生成与数据量控制index.py 读入模板后典型做法是把$content替换成完整的文章列表 HTML。列表项生成放在 Python 侧用 f-string 循环拼接# index.py 的核心渲染函数 import json from string import Template from pathlib import Path def build_home(): template Template( Path(template.html).read_text(encodingutf-8) ) posts json.loads( Path(passages.json).read_text(encodingutf-8) ) cards [] for post in posts[:15]: # 首页只展示最近 15 篇 cards.append(f article h2a hrefmarkdown/{post[file]}.html{post[title]}/a/h2 time datetime{post[date]}{post[date]}/time p{post[summary]}/p p{ · .join(post[tags])}/p /article .strip()) html template.safe_substitute( page_title小型博客系统, content\n.join(cards), ) Path(index.html).write_text(html, encodingutf-8)这里有个容易被忽略的设计点posts[:15]是硬上限还是可配置项。文章积累到几十篇之后首页全量渲染会拖慢首屏我一般会把上限提成常量或从 config 读取。另一个细节是链接指向markdown/{file}.html意味着每篇 Markdown 还需要单独渲染成静态详情页这部分通常也在 index.py 里完成模板与首页复用同一份 template.html只是$content换成文章正文。classless.css 的存在也是有讲究的。它不定义.card、.btn这类语义类名而是直接给body、article、h1、a、time这些原生标签设样式。好处是模板里不需要维护一长串类名生成的 HTML 更换 CSS 后依然保持基本语义坏处是组件状态没有类名挂载点实现“当前导航高亮”这类效果时要额外写少量辅助类。整体适合“内容展示大于交互”的个人博客场景。3.3 详情页的最小 Markdown 渲染详情页不能直接输出原始 Markdown需要把content字段转成 HTML。因为项目不依赖第三方库常见做法是实现一个最小子集转换器#标题、-无序列表、引用、空行分段# index.py 中的 minimal_md_to_html只处理常用块级语法 def minimal_md_to_html(body): lines body.splitlines() html, ul_open, in_quote [], False, False for raw in lines: line raw.rstrip() if not line: if ul_open: html.append(/ul) ul_open False if in_quote: html.append(/blockquote) in_quote False continue if line.startswith(### ): html.append(fh3{line[4:]}/h3) elif line.startswith(## ): html.append(fh2{line[3:]}/h2) elif line.startswith(# ): html.append(fh1{line[2:]}/h1) elif line.startswith(- ): if not ul_open: html.append(ul) ul_open True html.append(fli{line[2:]}/li) elif line.startswith( ): if not in_quote: html.append(blockquote) in_quote True html.append(fp{line[2:]}/p) else: html.append(fp{line}/p) return \n.join(html)这段代码的边界是明确的它不处理代码围栏、不转义 HTML 实体、不支持嵌套列表。如果稿子里混入script会原样落到页面 DOM所以配合这条链路使用时markdown 目录要视为“只有你能写”的可信源不能做成多人提交的内容平台。答辩时如果被问安全隐患能答出这一点说明你对 XSS 有基本认知属于加分项。4. 检索与友链search.html 的客户端搜索和 friends.py 的批量生成4.1 fetch 拉取 passages.json 的关键词过滤search.html 不依赖服务端直接在前端 fetch passages.json在浏览器内存里过滤。对几百篇文章的小型博客这比在 Python 侧写搜索接口直接得多不需要维护进程、不需要处理并发、页面打开即用也天然支持静态部署。// search.html 中的搜索核心逻辑 const input document.getElementById(search-input); const list document.getElementById(result-list); let posts []; fetch(./passages.json) .then(res res.json()) .then(data { posts data; render(posts); }); function render(filtered) { list.innerHTML filtered.map(post li a hrefmarkdown/${post.file}.html${post.title}/a span${post.date}/span p${post.summary}/p /li ).join(); } input.addEventListener(input, (e) { const kw e.target.value.trim().toLowerCase(); if (!kw) return render(posts); render(posts.filter(p p.title.toLowerCase().includes(kw) || p.summary.toLowerCase().includes(kw) || (p.tags || []).some(t t.toLowerCase().includes(kw)) )); });注意toLowerCase()在纯中文检索场景是无效的——中文没有大小写概念命中判断实际靠includes完成。保留它是为了兼容混排英文文章标题里带“Python”用户搜“python”也能命中。真正的问题在于结果顺序保持了 passages.json 的原始排列没有相关性概念。要改进可以给不同字段的命中加权重分function score(post, kw) { if (post.title.includes(kw)) return 2; if ((post.tags || []).some(t t.includes(kw))) return 1; return 0; } posts.filter(p p.title.includes(kw) || p.summary.includes(kw) || (p.tags || []).some(t t.includes(kw)) ).sort((a, b) score(b, kw) - score(a, kw));命中位置权重排序效果title 包含关键词2最靠前tags 包含关键词1中间位置summary 仅包含0排在最后这套规则没有引入 TF-IDF 或 BM25但对小型博客已经够用。答辩 PPT 里可以写“基于关键词匹配的客户端检索”不建议写“全文检索”或“搜索引擎”后者在技术上不太准确。4.2 friends.py 从 JSON 生成友链卡片friends.json 是友链的数据源把友链信息从 HTML 里抽出来再生成页面收益体现在更新场景新增友链时不用翻 HTML 找插入点只改 JSON 数据重跑 friends.py。数据结构一般长这样{ friends: [ { name: 示例博客, url: https://example.com, desc: 后端与运维笔记, avatar: https://example.com/avatar.png } ] }对应的生成逻辑有一个边界要处理avatar字段为空时不能渲染img标签否则页面会留下破图。常见做法是给首文字母渲染一个背景色块兜底# friends.py从 JSON 渲染友链卡片列表 import json from pathlib import Path data json.loads(Path(friends.json).read_text(encodingutf-8)) cards [] for f in data.get(friends, []): name f[name] url f[url] desc f.get(desc, ) if f.get(avatar): avatar_html fimg src{f[avatar]} alt{name} else: avatar_html fspan classavatar-fallback{name[0]}/span cards.append( fa classfriend-item href{url} target_blank relnoopener f{avatar_html} fspan classfriend-name{name}/span fspan classfriend-desc{desc}/span f/a ) Path(friends.html).write_text( \n.join(cards), encodingutf-8 )target_blank与relnoopener必须成对出现这是防止反向 tabnabbing 的基本要求。data.get(friends, [])保证 JSON 结构不完整时代码不会直接抛 KeyError属于健壮性细节。如果你希望友链按名称拼音排序可以在循环前加data[friends].sort(keylambda x: x[name])中文环境下这个排序结果不一定符合预期更稳的做法是在 JSON 里手动维护期望顺序。5. 本地跑通与增量调试http.server 验证和构建链优化5.1 内置 HTTP 服务与文件协议差异index.py 生成的是静态 HTML直接双击 index.html 虽然能看首页但 search.html 里fetch(./passages.json)在浏览器file://协议下会触发 CORS 限制Chrome 控制台会报跨域错误搜索功能直接不可用。最稳妥的验证方式是用 Python 标准库起本地服务python -m http.server 8000 --bind 127.0.0.1-m http.server调用标准库 HTTP 服务器8000是端口被占用就换8080或9000--bind 127.0.0.1只监听本机回环地址不会暴露到局域网。如果想让手机在同一 WiFi 下访问可以把参数改成--bind 0.0.0.0但要先确认网络归属和防火墙策略再操作。注意绑定0.0.0.0会监听所有网卡公共 Wi-Fi 环境下不要随意使用优先127.0.0.1。启动后在浏览器访问http://127.0.0.1:8000/index.html确认首页渲染再打开http://127.0.0.1:8000/search.html输入关键词验证搜索。如果搜索无响应优先打开开发者工具的 Network 面板确认 passages.json 是否成功加载、响应头是否为application/json。如果终端提示python was not found说明 Python 未加入 PATH重新安装时勾选 Add Python to PATH 再重开终端。5.2 构建命令串行与 JSON 可读性修改一篇 Markdown 后手动跑 process.py 再跑 index.py 再刷新浏览器来回切终端很消耗注意力。把三步串成一个命令python process.py python index.py python friends.py的意义在于前一步退出码为 0 才执行下一步任何一个脚本抛异常都会中断方便立刻定位是解析阶段还是渲染阶段出错。配合 VS Code 可以把这行命令写入.vscode/tasks.json配置自定义任务用快捷键触发。最后Windows 下容易忽略的是 PowerShell 输出编码问题。process.py 里 json.dump 如果不加ensure_asciiFalse中文会被转写成\uXXXX序列浏览器能解析但调试起来很难受# process.py 写入 passages.json 时的推荐参数 with open(passages.json, w, encodingutf-8) as f: json.dump(posts, f, ensure_asciiFalse, indent2)ensure_asciiFalse保留中文字符原始形态indent2让 JSON 按层级缩进这两项直接影响答辩现场的调试体验——评委看到的是可读的结构化数据而不是一行上万字符的压缩串。本文还有配套的精品资源点击获取