23周全栈Python入门教程PDF：学习计划、环境搭建与检索知识库

简介：千锋教育Python入门教程PDF面向K12阶段学生及零基础编程自学者，围绕Python从语法入门到方向认知的路径整理，帮助读者在投入视频课程前建立清晰的知识地图与学习顺序。文件为1个PDF文档，体积约663KB，内容以文字纲要和课程导览为主，轻量易读，适合在电脑或移动端快速浏览。教程覆盖变量、数据类型、控制流、函数与模块等语言基础，并延伸至异常处理、面向对象、第三方库、PyQt界面开发、Linux指令与Shell、数据库操作、HTML/CSS与JavaScript前端基础、爬虫、Django/Flask网站后台、机器学习、数据分析及树莓派物联网等主题，同时列出网站后端、自动化运维、数据分析、自动化测试、游戏脚本等Python应用方向。已有992人学习，可作为了解千锋Python课程体系、规划全栈学习路线与筛选后续专题的参考材料。

1. 一份 23 周全栈体系的 Python 入门教程 PDF，拿到手先看目录的顺序

给初学者找 Python 入门教程 PDF，最常见的误区不是资源太少，而是拿到一份动辄几百页、覆盖 10 个阶段的讲义，翻开第一页就开始抄代码，抄到第 4 章发现前面缺了 Linux 基础，抄到第 9 章发现根本不知道 NumPy 是干什么的。这份讲义属于典型的“机构内部教学大纲成册”形态：从 Python 2.7.3 与 3.x 双版本语法讲起，一路铺到 Linux 指令、Shell、数据库、HTML/CSS/JavaScript、Django/Flask 后台、爬虫、数据分析与机器学习，最后还带了 PyQt 桌面开发和树莓派硬件交互。它更像一张完整的能力地图，而不是从头到尾顺读的小说。

把它当 k12 python 文档资料用也成立：目录清晰、知识点密度均匀、每节都配练习方向，家长或老师照着排课能直接用。适合三类人：完全零基础想系统过一遍的自学者、需要一份现成课程骨架的培训从业者、以及想给孩子做编程启蒙但自己不懂技术的人。不适合指望“三天上手写项目”的人，因为它的价值在体系，不在速成。

2. 拆目录：把 10 个阶段映射成一张能执行的 23 周计划表

拿到讲义先别读正文，先把目录拆成表。原因很实际：讲义是按知识模块排列的，教学顺序和自学顺序不是一回事。机构上课有老师兜底，自学没有人告诉你“这一节可以跳”。我一般会做三件事——归并阶段、标注先修、砍掉选修。做完这三步，几百页的内容就变成了一条有先后依赖的线。

2.1 先把散落的知识点归并成 10 个阶段

讲义原文列出的知识点比 10 个多，什么 PyQt、Shell、Kali、树莓派、微信公众号都散在各处。按“能不能独立成周”的标准重新归并，得到下面这张表。这一步的意义是让后面排周计划时有稳定的输入，不至于每周都改一次计划。

表里“选学”的判定标准只有一条：不学它，能不能把后面的必修课跑通。S4 运维自动化依赖的是 Linux 命令手感，S9 依赖的是 NumPy 的数组思维，这两块如果时间紧，先放着不影响主线。S10 属于兴趣拓展，什么时候看都行，但别放在 S8 之前，容易把节奏带偏。

2.2 用一段脚本把阶段表压成 23 周日程

手排 23 周容易出错，尤其是中间要插缓冲周、要按每周可投入小时数动态伸缩的时候。下面这段脚本读上面的阶段表，输出一份带起止日期和累计学时的 CSV，直接导入表格软件就是一张日程表。

# build_plan.py import csv from datetime import date, timedelta # (编号, 名称, 基准周数, 是否必修) STAGES = [ ("S1", "Python 语言基础", 3, True), ("S2", "Python 3.x 进阶与第三方库", 3, True), ("S3", "Linux 指令与 Shell", 2, True), ("S4", "Linux 运维自动化", 2, False), ("S5", "数据库开发", 2, True), ("S6", "前端基础 HTML/CSS/JS", 3, True), ("S7", "Web 后台 Django/Flask", 3, True), ("S8", "爬虫与自动化测试", 2, True), ("S9", "数据分析与机器学习", 2, False), ("S10", "PyQt 与树莓派", 1, False), ] START = date(2025, 3, 3) # 起始周的周一 HOURS_PER_WEEK = 10 # 每周可投入学时 BUFFER_EVERY = 5 # 每学 5 周插 1 个缓冲周 ONLY_REQUIRED = True # 是否只排必修阶段 def build(start, hours, buffer_every, only_required): rows, week_no, cursor = [], 1, start for sid, name, weeks, required in STAGES: if only_required and not required: continue begin = cursor for _ in range(weeks): cursor += timedelta(days=7) rows.append({ "阶段": sid, "内容": name, "周次": f"W{week_no}-W{week_no + weeks - 1}", "开始": begin.isoformat(), "结束": (cursor - timedelta(days=1)).isoformat(), "学时": weeks * hours, "必修": "是" if required else "否", }) week_no += weeks # 每满 buffer_every 周插入一个缓冲周，用来补练习和回看 if week_no % buffer_every == 0: rows.append({"阶段": "BUF", "内容": "缓冲周：补练习 + 回看错题", "周次": f"W{week_no}", "开始": cursor.isoformat(), "结束": (cursor + timedelta(days=6)).isoformat(), "学时": hours, "必修": "是"}) cursor += timedelta(days=7) week_no += 1 return rows if __name__ == "__main__": plan = build(START, HOURS_PER_WEEK, BUFFER_EVERY, ONLY_REQUIRED) with open("plan.csv", "w", newline="", encoding="utf-8-sig") as f: writer = csv.DictWriter(f, fieldnames=list(plan[0].keys())) writer.writeheader() writer.writerows(plan) print(f"共 {len(plan)} 行，课程周 {plan[-1]['周次']}")

逻辑上分三步：先按weeks字段累加日期游标，再在满buffer_every周的位置插一个缓冲周，最后一次性写 CSV。START定在周一，是为了让“每周复盘”有个固定锚点；HOURS_PER_WEEK只影响“学时”列，不改变周数，想压缩周期就改各阶段weeks；ONLY_REQUIRED=True会滤掉 S4、S9、S10，排出来大约是 18 周加 3 个缓冲周，正好 21 周上下，留了两周余量应对生病、加班这类现实变量。缓冲周不是可选项，跳过缓冲的自学计划几乎都会在第八周左右崩掉，血泪经验。

2.3 哪些章节现在就该划掉，哪些必须回头补

划掉的部分有三块。第一块是 Python 2.7.3 的专属语法章节，讲义为了照顾历史教学环境保留了这部分，现在照做只会浪费时间，当成“了解历史上长什么样”翻一遍即可。第二块是安全测试类章节，对零基础读者来说先修知识跨度过大，建议整段跳过，等有网络基础再回来。第三块是树莓派硬件部分，没有板子就纯看文字，收益极低。

必须回头补的是 Linux 命令行。这份讲义把它排在第三阶段，但后面数据库、后台开发、爬虫部署全都要求你在终端里能自如地cd、grep、看进程。我见过不少人卡在 Django 启动那一步，报错信息其实很直白，就因为不习惯看终端输出而放弃。补的方式很简单：把讲义里的 Shell 章节过一遍后，强制自己用命令行完成两周日常操作，不用图形界面文件管理器。

3. 环境落地：Python 2.7.3 和 3.x 并存时怎么装不冲突

讲义里的示例代码横跨两个大版本，这是它最容易被吐槽的地方，也是最容易让新手劝退的地方。直接把 2.7.3 装到主环境是下策，现代操作系统上装它要先降级 OpenSSL，装完还会污染 PATH。合理做法是：主环境只保留一个 3.x，2.7 单独放容器或独立前缀里，只在需要对照讲义老例子时调用。

3.1 为什么不能照着讲义直接装 2.7.3

Python 2.7 早在 2020 年就停止维护，官方不再出安装包，第三方库也基本不再发布对应的二进制轮子。你在新系统上pip install一个稍微新一点的包，要么报SyntaxError（包源码用了 3.x 语法），要么进入源码编译并卡在 OpenSSL 头文件上。讲义写的时候这套环境还是主流，现在不是了。

所以策略要反过来：把 3.x 当工作环境，把 2.7 当“阅读环境”。看老语法章节时不必真跑，跑不通的地方用 3.x 改写一遍，反而是一次很好的差异对照练习。这个转换过程本身就是学习，比死磕旧环境划算得多。

3.2 用容器隔离 2.7，用 venv 隔离 3.x 的项目

主环境用系统包管理器或官方安装包装一个 3.10 以上的版本，之后每个项目建独立 venv。2.7 只在需要时用容器起一个临时解释器，用完即删，不落痕迹。

# 1) 确认主环境版本（要求 3.10+） python3 -V # 2) 为讲义练习建一个独立虚拟环境，避免污染系统 site-packages python3 -m venv ~/venvs/pybasic source ~/venvs/pybasic/bin/activate # Windows: .\venvs\pybasic\Scripts\activate # 3) 确认当前解释器路径，防止装错地方 python -c "import sys; print(sys.executable)" # 4) 需要对照 2.7 老例子时，临时起一个容器（用完即退） # docker run --rm -it -v "$PWD":/work -w /work python:2.7-slim python old_demo.py

python3 -m venv是标准库自带，不需要额外装 virtualenv；激活后务必跑一次sys.executable，输出应该指向~/venvs/pybasic/bin/python，如果还指向系统路径，说明激活没生效，后面所有pip install都会装到全局去。第 4 行的容器命令是注释状态，需要时再解开，注意挂载目录用绝对路径，相对路径在某些终端下会被解析成空目录。

3.3 依赖清单和镜像源：让 pip 少折腾

讲义涉及的第三方库横跨数据分析、Web、爬虫三类，一次全装会拖很久，也容易版本冲突。按阶段拆成几个 requirements 文件，装哪个阶段用哪个。国内网络环境下配置一个镜像源能省不少等待时间。

# ~/.config/pip/pip.conf（Windows 为 %APPDATA%\pip\pip.ini） # [global] # index-url = https://pypi.tuna.tsinghua.edu.cn/simple # timeout = 30 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.timeout 30

# requirements-s1.txt —— 基础语法阶段基本不用装东西，这几行是练习用的 ipython==8.24.0 requests==2.32.3 # requirements-s5.txt —— 数据库阶段 pymysql==1.1.1 cryptography==42.0.8 # requirements-s9.txt —— 数据分析与机器学习阶段 numpy==1.26.4 pandas==2.2.2 matplotlib==3.9.0 scikit-learn==1.5.0

版本号锁死是有意为之。讲义里的示例代码写在若干年前，用最新版库跑很可能遇到 API 改名（比如 pandas 里一批旧参数被移除）。锁到一个稳定的次版本，先把讲义例子跑通，再考虑升级。cryptography单独列出来是因为新版 MySQL 的认证插件依赖它，不装会在连接时报认证失败，这个坑很隐蔽。

3.4 三步自检：环境到底通没通

装完不要急着写业务代码，先跑一段自检脚本，把解释器版本、关键模块、编码、路径四件事一次确认掉。这段脚本建议存成check_env.py，每换一台机器都跑一次。

# check_env.py —— 环境自检，任何一项失败就先解决再往下学 import sys import platform import sqlite3 import importlib.util CHECK_MODULES = ["requests", "pymysql", "numpy", "pandas"] def main(): print(f"解释器版本 : {sys.version.split()[0]}") print(f"可执行文件 : {sys.executable}") print(f"操作系统 : {platform.system()} {platform.release()}") print(f"默认编码 : {sys.getdefaultencoding()} / 文件系统 {sys.getfilesystemencoding()}") print(f"SQLite : {sqlite3.sqlite_version}") # 逐个探测模块是否存在，不导入，避免慢库拖时间 for name in CHECK_MODULES: ok = importlib.util.find_spec(name) is not None print(f"{'[OK] ' if ok else '[MISS]'} {name}") if __name__ == "__main__": main()

find_spec只查模块能否被找到，不真正执行导入，所以对 numpy 这种导入慢的库很友好。输出里[MISS]的行就是当前阶段还不需要或者装漏的，按阶段补即可，别一次全补齐。sys.executable那一行是重点中的重点，它告诉你现在到底在用哪个解释器，虚拟环境有没有生效一眼就能看出来。

4. 从语法练习到能跑的小工具：把讲义章节变成可验证的代码

讲义前六章的写法是“讲解 + 示例 + 练习方向”，练习方向往往只有一句话，比如“实现一个统计字符串中出现次数最多的字符”。这种题的训练密度其实不低，问题在于没人给你对答案。我的做法是每学完一节，把它扩成一个能读文件、能输出结果、能处理异常的小工具，哪怕只有三十行。工具跑通了，这一节才算过。

4.1 基础语法：用一个词频统计把字典、循环、函数串起来

数据类型、控制流、函数这三块在讲义里分了三节，但它们本来就是一件事。写一个读文本、清洗、计数的脚本，三块知识一次用上，比做十道选择题有用。

# word_stat.py —— 统计文本里的高频词 import re from collections import Counter from pathlib import Path # 只保留字母和中文字符，其余当分隔符处理 TOKEN_RE = re.compile(r"[A-Za-z]+|[\u4e00-\u9fa5]+") STOPWORDS = {"the", "and", "for", "with", "that", "this", "是", "的", "了"} def tokenize(text: str) -> list[str]: """把文本切成小写词元，过滤停用词和单字符""" words = (w.lower() for w in TOKEN_RE.findall(text)) return [w for w in words if len(w) > 1 and w not in STOPWORDS] def top_words(path: str, n: int = 15, encoding: str = "utf-8") -> list[tuple[str, int]]: """返回出现次数最多的 n 个词及其频次""" text = Path(path).read_text(encoding=encoding, errors="ignore") counter = Counter(tokenize(text)) return counter.most_common(n) if __name__ == "__main__": for word, cnt in top_words("sample.txt", n=15): print(f"{word:<10}{cnt:>6}")

tokenize里的正则用了两个分支：英文按连续字母切，中文按连续汉字切，中间不插空格的中英混排也能处理。errors="ignore"是为了绕开一些老文本文件的编码问题，代价是会丢掉少量字符，练习场景够用。n控制输出条数，encoding建议显式传，Windows 上默认 GBK 读 UTF-8 文件会直接抛UnicodeDecodeError，这种报错信息看着吓人，其实改一个参数就解决。

写完对照一下讲义里的示例，看它用的sorted(d.items(), key=lambda x: x[1], reverse=True)和Counter.most_common有什么区别。前者是通用排序思路，后者是专门给计数场景优化的结构，讲义讲排序时用前者，讲集合时用后者，你把两种都跑一遍，理解会扎实很多。

4.2 文件操作与异常处理：讲义最容易翻过去的两节

这两节在目录里只占几页，但实际工作中用得最多。讲义给的例子大多是“打开文件、读、关闭”，现代写法更推荐with加生成器。异常处理部分要给一个真实的失败路径，不然读者永远不知道except该捕获什么。

# safe_read.py —— 带重试与降级编码的读取器 import logging from pathlib import Path logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s") class EmptyFileError(ValueError): """自定义异常：文件存在但内容为空""" def read_lines(path: str, encodings=("utf-8", "gbk")): """逐行读取，编码失败时自动降级重试""" p = Path(path) if not p.exists(): raise FileNotFoundError(f"文件不存在: {p.resolve()}") if p.stat().st_size == 0: raise EmptyFileError(f"文件为空: {p.name}") for enc in encodings: try: with p.open("r", encoding=enc) as f: for line in f: yield line.rstrip("\n") return # 读完正常退出，不再尝试下一个编码 except UnicodeDecodeError: logging.warning("编码 %s 解码失败，尝试下一个", enc) raise UnicodeDecodeError("utf-8", b"", 0, 1, "所有候选编码均失败")

用生成器的好处是大文件不会一次性读进内存，讲义里的readlines()在几十 MB 的文件上就会开始卡。编码降级的顺序按常见程度排，utf-8失败再试gbk，两条都不行才抛错。自定义EmptyFileError继承ValueError而不是Exception，是为了让调用方用except ValueError就能一并接住，异常分层这件事讲义没细讲，但你在写第二个工具时就会需要它。

调用侧要写清楚捕获顺序：先捕获最具体的，再捕获宽泛的。把FileNotFoundError放在OSError前面，否则宽泛的那个会先接住，日志里就看不到具体原因了。

4.3 数据库章节：先用 SQLite 打通 SQL 手感，再换 MySQL

讲义把数据库排在第五阶段，讲的是连接、建表、增删改查、事务。直接在 MySQL 上练有个现实问题：新手装 MySQL 经常卡在服务起不来、端口占用、认证插件不匹配。更省事的路径是先用标准库自带的 SQLite 把 SQL 语句写熟，再切到 MySQL，只换连接层。

# db_demo.py —— SQLite 与 MySQL 双份连接示例 import sqlite3 def with_sqlite(db_path: str = "demo.db"): # isolation_level=None 表示手动提交，事务边界看得见 conn = sqlite3.connect(db_path, isolation_level=None) conn.row_factory = sqlite3.Row # 让查询结果支持按列名取值 cur = conn.cursor() cur.execute("CREATE TABLE IF NOT EXISTS score(" "id INTEGER PRIMARY KEY, name TEXT NOT NULL, point REAL)") cur.execute("BEGIN") try: cur.executemany("INSERT INTO score(name, point) VALUES(?, ?)", [("A同学", 88.5), ("B同学", 92.0), ("C同学", 76.0)]) cur.execute("COMMIT") except Exception: cur.execute("ROLLBACK") raise rows = cur.execute("SELECT name, point FROM score ORDER BY point DESC").fetchall() conn.close() return [dict(r) for r in rows] # 切到 MySQL 时只改连接串，SQL 语句基本不动 # import pymysql # conn = pymysql.connect(host="127.0.0.1", port=3306, user="dev", # password="***", database="demo", charset="utf8mb4", # cursorclass=pymysql.cursors.DictCursor)

isolation_level=None关掉 SQLite 的自动提交，这样BEGIN和COMMIT的边界完全由你控制，事务那一节讲的东西才能被观察到。row_factory = sqlite3.Row让查询结果能按列名访问，省去记住下标。切 MySQL 的注释块里charset="utf8mb4"别省，中文和 emoji 都会用到它，不少连接失败报的是乱码而不是错误码，排查起来很绕。

4.4 爬虫章节：先写一个守规矩的单页抓取器

讲义的爬虫部分知识点很密，从请求到解析到存储都有。刚上手不要一上来就写多线程爬全站，先写一个只抓单页、有限速、有超时、能识别编码的最小版本，跑通了再往后加功能。

# fetch_one.py —— 单页抓取，只做公开静态页面练习 import time import requests from bs4 import BeautifulSoup HEADERS = {"User-Agent": "Mozilla/5.0 (study-bot; contact: none)"} TIMEOUT = 10 DELAY = 1.5 # 两次请求之间的最小间隔，秒 def fetch_title(url: str) -> str: time.sleep(DELAY) # 限速放在发请求之前，最简单也最有效 resp = requests.get(url, headers=HEADERS, timeout=TIMEOUT) resp.raise_for_status() # 4xx/5xx 直接抛，不带着错误页面往下解析 resp.encoding = resp.apparent_encoding soup = BeautifulSoup(resp.text, "html.parser") return soup.title.get_text(strip=True) if soup.title else "(无标题)" if __name__ == "__main__": print(fetch_title("https://example.com/"))

raise_for_status()是关键的一行，很多新手脚本抓不到东西是因为服务器返回了 403 或 404，代码却继续拿错误页去解析，最后得到空列表还以为是选择器写错了。apparent_encoding会根据内容猜编码，比固定utf-8稳。DELAY放在请求之前而不是之后，是为了让“第一次请求”也不至于密集触发。练习请只针对公开的、允许抓取的静态页面，先看一眼目标站点的 robots 协议和频率限制，别把练习变成给别人添麻烦。

5. 避坑：照着一份老讲义自学最常翻车的 5 个地方

这份讲义的内容跨度大、写作年代偏早，踩坑点集中在两类：环境和版本，以及学习路径和依赖。下面五条是我在不同机器上反复遇到过的，按“现象 → 原因 → 解决”写，遇到了直接对号入座。

5.1 环境与版本类的三个坑

坑一：装 2.7.3 时装到一半报编译错误。

现象：执行安装或pip install时报缺少openssl/ssl.h，或者编译到_ssl模块直接失败。 原因：新版系统的 OpenSSL 已经是 3.x，2.7 时代的编译脚本不认识新头文件位置，而且官方早就不再发布适配的预编译包。 解决：不要在主力机上装 2.7。用容器临时跑，或者干脆放弃运行、只做语法对照阅读，把讲义里的老例子改写成 3.x 版本再执行。改写的过程比运行旧代码更有价值。

坑二：虚拟环境明明激活了，pip install还是装到了全局。

现象：pip list里能看到刚装的包，但python xxx.py报ModuleNotFoundError。 原因：终端里python指向的解释器和pip指向的不是同一个，Windows 上 PATH 里系统 Python 排在前面时尤其常见；另一个常见原因是习惯性写了sudo pip install。 解决：一律用python -m pip install 包名，让 pip 跟着当前解释器走；每次激活后跑python -c "import sys; print(sys.executable)"确认路径。养成这个习惯以后，这类问题基本不再出现。

坑三：讲义里的print "hello"报语法错误。

现象：照着敲示例代码，第一行就SyntaxError: Missing parentheses in call to 'print'。 原因：讲义混排了 2.x 和 3.x 两套语法，print语句、整数除法、dict.keys()返回值、字符串编码这四处差异最集中。 解决：建一张自己的差异对照表，每遇到一处就记一行，统一按 3.x 写。老代码只读不改，改也只改成 3.x 版本。这张表写到二十行左右，你对两个版本的差异就有了肌肉记忆。

5.2 学习路径与依赖类的两个坑

坑四：按周计划推进，卡在数据分析章节动不了。

现象：Pandas 的示例跑起来全是KeyError和SettingWithCopyWarning，换几个版本还是一样。 原因：通常是跳过了 NumPy 直接上 Pandas，或者用了与讲义不匹配的新版本库，append、inplace这类旧写法在新版里行为变了。 解决：回填 NumPy 的数组与索引基础，再把 pandas 锁到讲义成书年代的次版本（比如 1.x 的最后一个版本）先把例子跑通，跑通之后再迁移到新版并按官方迁移指南改。别一边学语法一边调版本，两件事叠在一起很难判断问题出在哪。

坑五：PDF 目录页码和视频目录对不上，找不到对应小节。

现象：想找“字典的常用方法”这一节，PDF 里翻不到，视频目录里也没有完全对应的标题。 原因：讲义是教学大纲成册，视频是按课时录的，两套编号体系不一致，章节名也有缩写和改写。 解决：花一个小时做一张页码索引 CSV，三列——讲义页码、章节名、对应视频编号。做一次，后面几个月都省事，而且做索引的过程本身就是把目录完整过一遍，对整体结构会更清楚。

6. 进阶：把这份 PDF 变成可检索的本地知识库，顺带验证学习效果

几百页的讲义，真正高频回看的其实只有几十处。与其每次翻目录，不如花二十分钟把 PDF 抽成文本、切页、建一个最简的关键词检索，命令行里敲一个词就能定位到页码。这个练习还有个副作用：它把文件读写、字符串处理、字典、命令行参数几块知识全串了一遍，是检验前几章学没学扎实的现成考题。

# pdf_index.py —— 抽取文本 + 关键词检索 import json import re import sys from pathlib import Path import pdfplumber CACHE = Path("pages.jsonl") def build_cache(pdf_path: str, out: Path = CACHE) -> None: """逐页抽文本，写入 jsonl，一行一页""" with pdfplumber.open(pdf_path) as pdf, out.open("w", encoding="utf-8") as f: for i, page in enumerate(pdf.pages, start=1): text = page.extract_text() or "" text = re.sub(r"\s+", " ", text).strip() # 压缩空白，便于匹配 f.write(json.dumps({"page": i, "text": text}, ensure_ascii=False) + "\n") def search(keyword: str, topk: int = 8): """按关键词命中次数排序，返回页码与上下文片段""" hits = [] with CACHE.open(encoding="utf-8") as f: for line in f: rec = json.loads(line) n = rec["text"].lower().count(keyword.lower()) if n: idx = rec["text"].lower().find(keyword.lower()) hits.append((n, rec["page"], rec["text"][max(0, idx - 40): idx + 60])) return sorted(hits, key=lambda x: -x[0])[:topk] if __name__ == "__main__": if len(sys.argv) < 2: sys.exit("用法: python pdf_index.py 关键词 [pdf路径]") kw = sys.argv[1] if len(sys.argv) > 2: build_cache(sys.argv[2]) if not CACHE.exists(): sys.exit("请先提供 PDF 路径构建缓存") for cnt, page, snippet in search(kw): print(f"p{page:<4} 命中{cnt:>2}次 …{snippet}…")

extract_text()对扫描版 PDF 返回空字符串，如果你的讲义是图片版，得先过一次 OCR，这一步跳过会导致整个缓存全是空行，检索永远没结果——先随便抽一页看看有没有字，再决定要不要继续。re.sub(r"\s+", " ", text)把换行和多余空格压成单空格，是为了让跨行的关键词也能被匹配到，代价是丢掉了原始排版，做片段预览够用。topk控制返回条数，一般 5 到 8 条就够，多了反而要自己再筛一遍。

检索结果按命中次数降序排，而不是按页码排，这样重点章节会自己浮上来。用一段时间你会发现，被反复命中的那十几页就是这门课真正的核心，剩下的大段内容属于一次读完就够的背景知识。这时候再回头看第 2 章那张阶段表，可以按实际命中情况调整周数分配，把时间往高频页上压。

接下来还可以把pages.jsonl丢给一个本地分词工具，统计高频术语，反向生成一份自己的术语表。术语表比目录更能反映一份讲义的重点，也更容易在复习时派上用场。

从那以后我拿到任何一份几百页的讲义，都会先跑一遍目录拆表和文本索引这两步，再决定从哪一页开始读。不这么走一遍，很容易在前言和第一章里磨掉热情，然后在第四章某个环境报错上彻底停下。资源本身就在那儿，怎么把它变成一条能走完的路，才是要花心思的地方。希望帮到你。

本文还有配套的精品资源，点击获取