简介：《python 3.13版本中文文档资料》是一套面向中文Python学习者和开发者的离线HTML文档包，适合在无网络环境下查阅3.13版本的语言特性、标准库更新与迁移要点，也可作为新手入门和资深开发者跟进新版本的案头参考。压缩包共1269个文件，约15.57MB，以713个html页面为主体，配合507个txt辅助文本、21张png图示及少量js、css等资源，构成可本地浏览器直接打开的文档站点。已有435人学习下载，具备一定参考热度。内容围绕基础语法、数据结构、函数与面向对象、异常处理、标准库使用展开，并重点说明类型提示增强、性能改进、弃用功能替代及API变化，附带示例代码帮助理解。HTML形式便于电脑、平板和手机浏览，目录与索引清晰，适合系统通读、按章节检索和版本迁移时快速定位知识点。
1. 拿到 Python 3.13 中文文档离线版，先别急着双击 index.html
内网机器上写代码，最难受的不是没网，是想确认一个参数的默认值却只能靠记忆。这份 Python 3.13 中文文档离线版 HTML 资料解决的正是这个场景：整站编译好的静态页面，解压到本地就能翻，不依赖任何在线服务。它适合两类人——一类是机器常年不联外网、又必须用 3.13 新语法写代码的；另一类是手里同时装着好几个 Python 版本，需要一个随手能对照的本地参考。它本质上是 Sphinx 构建出来的静态站点，不是阅读器软件，双击 index.html 确实能看，但搜索框大概率是哑的。后面几章就从这个「能看不能搜」的裂缝开始拆。
2. 读懂离线包结构：Sphinx 构建产物里哪几个文件才是关键
拿到一个几百 MB 的文档目录，很多人第一反应是找 index.html，然后就没有然后了。其实这个目录的组织方式非常有规律，认清四类文件之后，你能做的事情会多出好几倍——搜索为什么失效、哪一页对应哪个模块、版本对不对得上，全都能从目录结构里读出来。这一章先把结构讲透，后面两章的操作才有落点。
2.1 顶层的四类文件：页面、源码、静态资源与索引
解压后的顶层目录，各家打包习惯不同，名字不纠结，但里面的东西基本固定是四类。第一类是渲染好的页面目录，tutorial、library、reference、howto、whatsnew、using 这几个是主干，library 下面按模块拆成一堆 html，一个模块一页，比如对应 pathlib 的那一页、对应 threading 的那一页。第二类是_sources，里面放的是每页对应的原始文本，多数构建保留.rst.txt后缀，也有打包时裁掉的，先确认一眼有没有。第三类是_static，样式、脚本、字体，还有几个关键 JS。第四类散在根上：index.html、genindex.html、py-modindex.html、searchindex.js、objects.inv。
这四类里，真正决定「好不好用」的是后两类。页面是给人看的，_sources和索引文件是给检索用的。我一般拿到包先做一件事：看一眼_sources在不在、searchindex.js多大。前者在，命令行全文检索就有戏；后者体量大，说明全文索引是全的，浏览器搜索能用，只是缺个 HTTP 环境。这两条判断做完，后面怎么用基本就定了。
还有个小细节值得留意：genindex.html是关键词总索引，按字母排的；py-modindex.html是模块索引，只列标准库模块。想快速确认「3.13 里到底还有没有某个模块」，翻py-modindex.html比一页页点快得多，尤其在第 4 章要核对被移除的那些老模块时。
2.2 searchindex.js 与 objects.inv：离线包的两条命脉
searchindex.js是 Sphinx 的主题搜索索引，里面存的是词条到文档 ID 的映射表，加上一份文档 ID 到标题/URL 的对照。浏览器打开页面后，_static/searchtools.js会去加载它，加载成功搜索框才工作。这里的加载走的是异步请求，不是<script>标签直接引入，所以它对「页面从哪来」是有要求的——这一点在第 5 章的坑里还会再撞一次。
objects.inv更容易被忽略。它是 Sphinx 的交叉引用清单，记录了全站所有可被引用的对象：模块、函数、类、方法、异常、数据、命令，每条带一个相对 URL。压缩包里它是 zlib 压过的，不能直接看，但解开之后就是一张极干净的「符号 → 位置」表。我把它当成这份离线资料里最有价值的副产品：拿它生成一张模块速查表，比在浏览器里翻侧边栏快得多，第 3 章会给具体脚本。
顺带说清一个常见误解：searchindex.js只索引正文词语，不索引代码块里的标识符。也就是说你在搜索框里敲一个函数名，未必能命中它所在的那一页；而objects.inv恰好补上这块，它存的正是符号名。两条路互补，别指望其中一条包打天下。
2.3 版本对齐：文档包版本号必须和解释器小版本对得上
这条在实操里被低估得最厉害。文档是 3.13.x 的，本机解释器是 3.12 或者 3.14，页面读起来毫无障碍，但你查到的 API 在本机根本不存在，或者行为差了一截。标准库章节尤其明显，3.13 这一轮改动集中在自由线程、交互式解释器、typing 和一批模块移除上，跨一个小版本翻错页，很容易得出相反结论。
我习惯在开始用之前先把两边的版本号摆在一起看：文档版本藏在_static/documentation_options.js的VERSION字段里，解释器版本python3.13 -c "import sys; print(sys.version)"一行就出来。两边主次版本对上了再往下走，对不上就换包，别硬凑。第 6 章会把这个比对写成一个固定脚本，每次换文档包跑一遍。
还有一层是「同一台机器装多个小版本」的情况，比如 3.13.1 和 3.13.5 并存。文档是给小版本发布的，微版本号差异通常不影响查 API，但如果你在排查某个已修复的 bug，就得留意页面底部的构建标记，别拿着旧页面的描述去对已经修掉的行为。
3. 三套检索方案：起本地服务、命令行全文搜、用 objects.inv 建模块索引
结构认清之后，接下来是让它真正好用的部分。这一章给三套方案，不是三选一，而是三种场景：边写边查用浏览器、批量找证据用命令行、查某个符号在哪一页用索引表。三套一起上，才叫「离线文档能用」。
3.1 用 http.server 把文档变成本地站点
这是解决搜索失效最直接的办法，不需要装任何东西，标准库自带。
# 进入解压后的文档顶层目录（里面能看到 index.html） cd ./python-3.13-docs-html-zh # 只监听本机回环地址，端口挑一个不冲突的 python3 -m http.server 8765 --bind 127.0.0.1这两行的作用是把当前目录当成站点根，用 HTTP 协议对外提供静态文件。--bind 127.0.0.1是关键参数，不写的话默认监听所有网卡，同一个局域网里别人也能连上你的文档站，房间里开着会的时候被同事扫到还挺尴尬。端口 8765 是随手挑的，避开常用的 8000、8080 就行，冲突了换一个数字重跑。
起好之后浏览器打开http://127.0.0.1:8765/index.html，搜索框敲个词试试，这时候应该能出结果了。原因是页面现在有了明确的同源地址，searchtools.js发起的异步请求能正常拿到searchindex.js，而在file://下这个请求会被拦掉。
想常驻的话，加一个简单脚本比自己记命令靠谱：
#!/usr/bin/env bash # docs-serve.sh —— 后台起服务，日志落到临时文件 DOC_DIR="${1:-./python-3.13-docs-html-zh}" PORT="${2:-8765}" cd "$DOC_DIR" || { echo "目录不存在: $DOC_DIR"; exit 1; } python3 -m http.server "$PORT" --bind 127.0.0.1 \ > /tmp/docs-serve.log 2>&1 & echo "pid=$! url=http://127.0.0.1:${PORT}/index.html"$!是后台进程号，想关的时候kill $(...)或者直接pkill -f "http.server $PORT"。日志重定向到/tmp是为了不污染终端，端口被占的时候去日志里能看到Address already in use，比对着一个没反应的浏览器猜要快。
提示：
http.server是单线程的，本地翻文档够用；如果几个人共用一台机器查，换成带并发能力的静态服务器会更稳，但那是另一件事了。
3.2 命令行检索 _sources：比浏览器搜索快的地方
浏览器搜索适合「我知道大概是什么，找那一页」，命令行适合「我要在所有页面里找出提到这个特性的地方」。如果你的包里有_sources，直接搜原始文本，速度比在界面里点快一个数量级。
# 找所有提到 full_match 的页面，只输出文件名 rg -l --glob '*.txt' 'full_match' _sources/library # 带行号和上下文，确认它是怎么描述的 rg -n -C 2 --glob '*.txt' 'full_match' _sources/library/pathlib.rst.txt-l只列文件不打印内容，适合先定位再细看；--glob '*.txt'限定只搜源码文本，避免误命中 HTML；-C 2带两行上下文，看描述是否完整。把范围从整个_sources收窄到_sources/library，是因为标准库的改动说明集中在那一块，whatsnew里则更多是汇总性的描述，两个地方的用途不一样。
没有rg也别折腾，grep 一样能干活：
# 递归搜，只输出文件名，忽略二进制 grep -rl --include='*.txt' 'full_match' _sources | sort--include='*.txt'等价于 rg 的 glob，-r递归，-l只列文件。慢一点，但到处都有。
我最常用的是这一条，用来抓某个特性在文档里的全部落点：
# 在 whatsnew 里找某个 PEP 编号出现的位置 rg -n --glob '*.txt' 'PEP 703|PEP 744' _sources/whatsnew输出会直接告诉你这两个编号分别落在哪一节，顺着行号往下读就行。这招在第 4 章核对自由线程和 JIT 的细节时特别好使，比在目录里一层层展开快。
3.3 解析 objects.inv 生成一份模块速查表
objects.inv是压缩的，但格式极其简单：前四行是明文头，剩下的是 zlib 压缩体，解压后每行一个条目，字段用空格分隔。写个二十行的脚本就能把它变成 CSV。
# parse_inv.py —— 解析 Sphinx 的 objects.inv，输出 类型/名称/URL import sys import zlib def iter_inv(path): with open(path, "rb") as f: # 前四行是明文头：版本行、Project、Version、压缩方式说明 for _ in range(4): f.readline() body = f.read() text = zlib.decompress(body).decode("utf-8") for line in text.splitlines(): # 按最多 5 段切，兼容不同 Sphinx 版本导出的字段数差异 parts = line.split(" ", 4) if len(parts) < 5: continue yield parts if __name__ == "__main__": inv = sys.argv[1] if len(sys.argv) > 1 else "objects.inv" for name, typ, prio, uri, disp in iter_inv(inv): print(f"{typ}\t{name}\t{uri}")逻辑说明：readline()四次跳过头部，剩下全部读进来做zlib.decompress；decode("utf-8")是必须的，中文文档包里有中文标题；split(" ", 4)限制最多切五段，因为最后一段显示名里可能带空格，不限制就会切碎。参数上，sys.argv[1]让脚本可以指向任意一个objects.inv，不传就默认当前目录，方便在不同版本的文档包之间来回切。
跑起来之后按类型过滤，直接产出模块索引：
python3 parse_inv.py ./objects.inv \ | awk -F'\t' '$1 ~ /^py:(module|function|class)$/' \ | sort -t$'\t' -k2,2 > modules.tsv # 查某个模块的所有条目 grep -P '\tpathlib\t' modules.tsv | head -20awk -F'\t'按制表符分列，$1 ~ /^py:(module|function|class)$/只保留三类，sort -k2,2按名称列排序。产出的modules.tsv可以直接丢进表格软件，或者当成本地搜索的数据源。我一般还会加一条，只导出模块级条目做成侧边目录，翻起来比 HTML 侧边栏紧凑。
三套方案的分工可以这样记：
| 方案 | 适合的场景 | 成本 | 局限 |
|---|---|---|---|
| http.server + 浏览器搜索 | 边写边查，凭印象找页面 | 一条命令 | 只索引正文词，不索引符号名 |
| rg 搜 _sources | 批量定位某特性在哪些页被提到 | 装个 rg | 依赖包里有 _sources |
| 解析 objects.inv | 查某个符号定义在哪一页 | 一个脚本 | 只有符号，没有解释文字 |
4. 按 3.13 的变化读文档：自由线程、JIT、新 REPL 与 typing 四条的查阅路径
3.13 这一轮的改动密度不低，而且有几项是「实验性」标签挂着的，文档写法跟常规 API 不一样，直接从头翻容易迷路。这一章按四条线给查阅路径，每条都配一个能在本机跑起来验证的片段。这么做的原因是：文档说的是「这一版支持什么」，本机跑出来的才是「你这台机器上有什么」，两者对不上是常态，尤其自由线程和 JIT 这两项，取决于解释器是怎么构建的。
4.1 自由线程：文档里怎么查、代码里怎么验
自由线程对应的是「去掉全局解释器锁」的那个构建变体，文档里集中在两块：whatsnew/3.13里的一节，以及using/configure或howto下关于构建选项的说明。查阅时用关键路径直接命中，别从首页点进去：
# 在源码文本里定位自由线程相关章节 rg -l --glob '*.txt' 'free-thread|GIL' _sources/whatsnew _sources/using命中的文件打开看，重点看三件事：这个构建产物的可执行文件名跟标准构建不一样、运行时可以用环境变量关掉 GIL、以及一批 C 扩展在无 GIL 下需要额外声明才安全。这三条是后续所有问题的根源。
验证本机到底是什么构建，跑这段：
# ft_check.py —— 判断当前解释器是不是自由线程构建 import sys import sysconfig # 标准构建没有这个属性，用 getattr 兜底，避免 AttributeError gil_enabled = getattr(sys, "_is_gil_enabled", lambda: True)() print("解释器版本 :", sys.version.split()[0]) print("GIL 当前状态:", "开启" if gil_enabled else "关闭") # Py_GIL_DISABLED 在编译期决定，1 表示自由线程构建 disabled = sysconfig.get_config_var("Py_GIL_DISABLED") print("编译期标记 :", disabled) print("是否自由线程构建:", bool(disabled))逻辑上分两层：sys._is_gil_enabled()是运行时状态，自由线程构建下也可能因为某些条件被重新打开；sysconfig.get_config_var("Py_GIL_DISABLED")是编译期事实，构建出来是什么就是什么，不会变。参数不用传，两个都是无参调用。判断顺序我一般先看编译期标记，None或0就直接结束，说明这是普通构建，后面关于无 GIL 的所有讨论都跟你无关。
如果确认是自由线程构建，再去看环境变量那一页，PYTHON_GIL的取值和-X gil的等价关系都写在那里。这块文档写得很细，但有个前提容易被跳过：只有在自由线程构建上这些开关才有意义，普通构建设了也是白设，这也是很多人照着文档设完发现没变化的原因。
4.2 实验性 JIT 与 REPL：文档说明与本地验证
JIT 这条线，文档里给的是「实验性」定位，构建开关和运行时开关分两处写。查阅路径是whatsnew里对应的那一节，加上构建说明里的编译选项。要点在于：主流发行版打包的解释器默认不开，所以你在本机import sys之后大概率什么也看不到，这不是你的问题。
探测代码很短，但要理解它为什么这么写：
# jit_check.py —— 探测 JIT 是否存在于当前构建 import sys jit = getattr(sys, "_jit", None) if jit is None: print("当前构建没有暴露 JIT 接口，通常是未启用实验性 JIT") else: print("JIT 可用:", jit.is_available()) print("JIT 已启用:", jit.is_enabled())getattr(sys, "_jit", None)兜底是因为这个接口在未启用的构建里根本不存在，直接sys._jit会抛 AttributeError。is_available()回答「这个二进制里编进去了吗」，is_enabled()回答「现在跑着吗」，两个值不一样很常见——编进去了但运行时可以关。
REPL 这块是 3.13 里体感最明显的一项，多行编辑、历史、颜色、直接粘贴多行代码不再报缩进错。文档在tutorial开头和whatsnew里都有描述。本机验证不用写脚本，直接开交互式解释器粘一段带缩进的代码进去，能一次贴完不炸就说明是新 REPL。想退回老行为排查兼容问题，设PYTHON_BASIC_REPL=1再起，这个开关在文档的对应页面里有写，属于排查兼容性问题时的后悔药。
4.3 标准库新增项：copy.replace、dbm.sqlite3、Path.full_match
新模块和新函数这一批，最省事的查法是从whatsnew的「新增模块」「改进的模块」两节往下扫，扫到感兴趣的再跳转到library对应页看完整签名。这里挑三个我自己用得上的，给验证片段。
# stdlib_new.py —— 3.13 新增能力的三个最小验证 import copy from dataclasses import dataclass import dbm.sqlite3 from pathlib import Path @dataclass class Conn: host: str port: int = 5432 timeout: float = 3.0 base = Conn("127.0.0.1") # 基于原对象派生一个新对象，原对象不变 print("replace :", copy.replace(base, port=6432)) print("原始对象 :", base) # 用 SQLite 做 dbm 后端，键值都必须是 bytes with dbm.sqlite3.open("/tmp/kv_demo.db") as db: db[b"k"] = b"v" print("dbm 读取 :", db[b"k"]) # 路径整串匹配，支持 ** 递归 print("full_match:", Path("/tmp/a/b/c.txt").full_match("/tmp/**/*.txt"))逻辑说明：copy.replace依赖对象实现__replace__，dataclass 在 3.13 里会自动生成，所以这个例子里不用手写；dbm.sqlite3.open的参数是文件路径，返回的对象支持字典式读写，但键值类型是 bytes，传字符串会直接抛错，这是最常见的翻车点；full_match和match的区别在于前者匹配整条路径、后者只匹配末尾部分，**的递归语义也和 glob 一致。
参数上还有一个容易忽略的点：copy.replace传的关键字必须是目标对象的字段名，拼错了不会静默忽略，会抛 TypeError，这比让你拿到一个字段没改的对象要友好。查文档的时候顺着library/copy那一页看__replace__的协议描述，比只看函数签名清楚。
4.4 typing 与「死电池」移除：迁移前必须翻的两页
typing 这一轮加的东西不少，类型参数默认值、只读 TypedDict 项、类型收窄的新写法，都在library/typing和whatsnew里。这类特性光看文字描述很难记住，最好的办法是在文档页里找到示例，粘到本地跑一遍类型检查器，看它认不认。文档示例通常是最小可复现的，比自己在项目里试错快。
更要紧的是「死电池」那一批模块的移除。这一轮按 PEP 594 的清单删掉了一批长期没人维护的老模块，涉及音频、终端、邮件、图片识别等方向。迁移动手之前，务必翻whatsnew里对应的移除章节，再对照py-modindex.html确认某个模块在新版里还在不在。查法如下：
# 从源码文本里抓被移除模块的清单段落 rg -n -A 3 --glob '*.txt' 'PEP 594' _sources/whatsnew # 确认某个模块在模块索引里是否还有条目 grep -c 'cgi' _sources/../py-modindex.html第一条命令的-A 3带三行后文，够看清清单开头；第二条是在渲染好的模块索引里数出现次数，0 就是没了。注意第二条的路径按你实际的包结构调整，别照抄。
我踩过一次相关的坑：一个老项目里import cgi一直能用，换到 3.13 之后直接 ImportError，报错信息很清楚，但当时没意识到是整批移除，还以为是环境问题，折腾了半天。从那以后，换大版本前先把移除清单过一遍成了固定动作。
5. 避坑：离线中文文档五个最容易翻车的点
这一章全是踩过的。每一条按「现象 → 原因 → 解决」写，遇到对得上的直接照做。
5.1 打开与目录层面的三个坑
坑一：双击 index.html，搜索框输入什么都返回空。
现象很明确：页面能正常显示，样式也在，就是搜索没结果，换关键词也一样。原因不是索引坏了，而是file://协议下searchtools.js发起的异步请求被拦掉了，searchindex.js根本没加载进来，搜索器手里没有数据。解决就是第 3 章那套，起一个本地 HTTP 服务，从http://127.0.0.1:端口/访问。别去改 JS 绕过限制，那是给自己挖坑。
坑二：中英文两个包解压到同一个目录，页面语言开始混着出现。
现象是有的页面中文、有的页面英文，搜索结果的标题也对不上点进去的内容。原因是两个包的文件名结构完全一样，后解压的把searchindex.js、objects.inv、_static里的资源全覆盖了，页面 HTML 却各自保留了一部分，于是索引和页面对不上。解决：一个版本一个目录，目录名带上语言和版本号，比如docs-3.13-zh、docs-3.13-en，永不合并。
坑三：Windows 上解压完，路径里带乱码，部分页面打不开。
现象是解压出来的文件名里有方块字或问号，点进去 404。原因是压缩包内的文件名编码和系统默认解压工具的猜测不一致，按本地代码页解出来就成了乱码。解决：换一个能显式指定编码的解压工具，或者干脆用 Python 自己解，zipfile在解压时可以指定文件名编码，处理完再打开目录确认一遍没有乱码文件。
5.2 版本与内容层面的两个坑
坑四：文档是 3.13，本机解释器是 3.12，照着页面写的代码跑不起来。
现象是复制了一段示例，报错说某个参数不存在，或者某个函数压根没有。原因就是版本错位，页面本身没错，错的是你拿它当本机版本的说明书用。解决：开工前先比对版本，文档版本从_static/documentation_options.js里读，解释器版本一行命令打出来，主次版本不一致就换包。第 6 章有现成脚本。
坑五：示例代码直接从页面复制，运行报 SyntaxError。
现象是粘进编辑器一跑，报语法错误，位置还指向>>>那一行。原因是文档里的示例是交互式会话格式，带提示符和续行符，本来就不是能直接执行的脚本。解决：手工去掉提示符，或者用doctest的方式把示例抽出来跑；更省事的办法是去_sources找同一段示例的源码文本，多数情况下那里也是带提示符的，但至少不会被 HTML 的排版字符干扰。真正要跑通，还是得自己重敲一遍，顺便也就记住了。
6. 把文档变成本地速查站：一条自检脚本和我的固定习惯
单机翻文档解决的是个人效率，如果是一台常开的机器，把它挂成一个局域网内可访问的本地站点，价值会翻倍——同一间屋子里几个人查同一份资料，不用每人解压一份。做法还是第 3 章那个 HTTP 服务，把绑定地址从127.0.0.1换成对内的网卡地址，端口固定，其他人用http://机器地址:端口/就能打开。目录名带上版本和语言，方便以后并存多个版本，页面上再加一个自己写的导航页，把whatsnew、genindex、py-modindex、常用几个模块页钉在最上面，比每次从首页点进去省事。
真正值得固定下来的是版本自检。换文档包、升级解释器、换机器，这三个动作之后都该跑一遍：
# check_docs_version.py —— 比对文档包与当前解释器的版本 import re import sys from pathlib import Path doc_root = Path(sys.argv[1] if len(sys.argv) > 1 else "./python-3.13-docs-html-zh") # 文档构建时会把版本号写进这个 JS，取 VERSION 字段 opt = doc_root / "_static" / "documentation_options.js" if not opt.exists(): sys.exit(f"找不到 {opt}，确认解压路径是否指到了顶层目录") m = re.search(r'VERSION:\s*"([^"]+)"', opt.read_text(encoding="utf-8")) doc_ver = m.group(1) if m else "unknown" py_ver = "%d.%d.%d" % sys.version_info[:3] print(f"文档版本 : {doc_ver}") print(f"解释器版本: {py_ver}") # 只比主次版本，微版本差异不影响查 API if doc_ver != "unknown" and not py_ver.startswith(".".join(doc_ver.split(".")[:2])): print("警告：主次版本不一致，标准库章节可能查到本机不存在的接口") else: print("版本对齐，可以放心用")参数就一个，指向解压后的顶层目录；不传则用默认路径。逻辑上只比对主次版本，因为微版本差异对查 API 没有实质影响，硬要比反而天天报警告，用两天就懒得看了。检测失败时退出码非零，方便塞进开机脚本或者 CI 里做前置检查。
还有一个我自己养成的习惯，算是血泪经验换来的：每次换到大版本，先不写代码，花十分钟把whatsnew里「移除」和「弃用」两节通读一遍，把命中的模块名记在一张纸上，然后拿项目里的 import 清单去比对。这一遍走完，能挡掉后面八成的 ImportError 和莫名其妙的 AttributeError。文档离线包最大的价值也在这儿——它让你在没有网络、没人可问的时候，还能把这件事做完。
希望帮到你。
本文还有配套的精品资源，点击获取
