简介这份Python 3.13中文离线文档面向希望系统掌握新版语言特性的初学者与进阶开发者适合在无网络环境下按章节查阅语法、标准库更新及版本迁移要点。压缩包共1269个文件以713个HTML页面和507个TXT文本为主体配合少量PNG插图以及JS、CSS等样式脚本整体约15.57MB用浏览器打开即可顺畅阅读。内容从基础语法、数据结构、函数编程延伸到面向对象、异常处理和标准库使用并重点梳理3.13的类型提示增强、性能改进、弃用功能与API变化配有示例代码辅助理解。已有435人学习下载可用于版本升级对照、项目兼容性排查和日常开发查阅也能帮助旧版本用户平滑过渡并减少踩坑。HTML版式支持电脑、平板和手机阅读适合作为离线案头手册随查随用尤其便于准备升级项目的开发者对照新特性与弃用项。1. 从一次断网查库的尴尬说起Python 3.13 中文离线文档到底该怎么装Python 3.13 版本的中文文档资料离线版 HTML 类型看着就是解压后双击index.html的事真到内网里查库时却经常翻车。前阵子在机房排一个pathlib行为差异的问题外网不通手机热点信号飘手边只有一份早前存下的 Python 3.13 中文文档压缩包。解压、双击、页面能开搜索框输入pathlib却没反应侧边栏点进去还有几个 404。最后改成用python -m http.server起了一个本地站点搜索和索引才正常。这套离线文档适合内网开发、经常出差、学校机房和不想每次查库都等在线页面的人。它不需要编译但很吃路径、权限和启动方式。下面按我实际落盘的顺序把版本选择、解压校验、本地 HTTP 服务、Nginx 配置和排错一次讲清。2. 装前环境清单Python 3.13 中文离线文档的版本对齐与依赖2.1 版本对齐3.13.0、3.13.1 与中文翻译进度先明确一件事Python 3.13 中文文档离线包不是解释器它是一套已经生成好的静态 HTML。你装不装 Python 3.13 解释器都能用浏览器打开它但要用http.server起服务机器上就得有 Python。很多人把“文档版本”和“解释器版本”混在一起结果查whatsnew时看到的是 3.13.0 的变更机器上跑的却是 3.13.1个别行为对不上就开始怀疑文档包坏了。我的做法是文档包的小版本尽量跟解释器小版本对齐。比如机器上主力是 3.13.1就优先找 3.13.1 对应的中文 HTML 包找不到完全一致的再用 3.13.0 的包但要记住差异通常集中在whatsnew/3.13.html和少量库页面。中文翻译还有一层滞后有些段落仍是英文这不是包损坏而是翻译进度没跟上。查库时以解释器实际行为为准文档用来定位 API 和参数不要拿它当唯一判据。另一个常见误区是拿 3.12 的文档包凑合看 3.13。3.13 在解释器层面有改动标准库页面也有新增和废弃标记跨小版本查库很容易把“已弃用”看成“还能用”。如果只是临时查语法凑合一下无妨要长期放在内网当参考站还是按 3.13 单独落一份。2.2 离线 HTML 包的目录结构index.html、search.html 与 _static解压后先别急着双击。Python 文档的 HTML 包通常是 Sphinx 生成的结构根目录下一般能看到这些入口路径/文件作用装的时候要注意什么index.html文档首页Nginx 的root必须指到它所在目录library/标准库页面子页面 404 时先查这一层reference/语言参考路径大小写敏感tutorial/入门教程一般不需要额外配置howto/专题指南静态文件只读即可whatsnew/版本变更和解释器小版本对齐时重点看_static/CSS、JS、字体权限不足时页面会“裸奔”_sources/reStructuredText 源码浏览器一般用不到别删search.html搜索入口必须通过 HTTP 访问才正常searchindex.js搜索索引用file://打开时容易被浏览器拦genindex.html总索引和搜索不是一回事py-modindex.html模块索引查标准库时很顺手这里最关键的是search.html和searchindex.js。搜索不是简单的页面内跳转它要加载索引文件浏览器在file://协议下会限制这类请求所以双击打开时“页面能看、搜索没反应”几乎必现。另一个关键是_static/如果 Nginx 权限没配好HTML 能返回但 CSS 和 JS 全是 403页面会变成纯文本堆叠看起来像文档包坏了。提示解压后先用find确认index.html的真实层级。有些压缩包顶层自带一个目录root指错一层首页能开子页面全 404。2.3 运行环境清单浏览器、解压工具与 Web 服务器怎么选这套东西对机器要求不高但几个组件不能缺。下面是我一般会先对一遍的清单组件最低可用我一般推荐说明浏览器近两年的 Chrome/Edge/Firefox最新稳定版太老的浏览器可能不认部分 JS解压工具unzip或 7-Zipunziptar先-l看目录再解压Python3.13 解释器与文档同小版本只用于http.server不装也能用 NginxWeb 服务器无Nginx 1.24长期给团队用建议上 Nginx磁盘压缩包解压后的空间预留一倍余量别塞满/分区权限只读账户可读root:docsvc 755/644不要图省事给 777如果只是自己本机查python -m http.server足够不用装 Nginx。要给小组内网共用或者要开机自启Nginx 更稳它能配 UTF-8、缓存、访问日志也能把文档站和别的服务隔开。Windows 上不想装 Nginx也可以用 Python 起服务后配计划任务但别用“双击 bat 窗口一直开着”这种办法机器一重启就没了。还有一点不要把文档包放在同步盘目录里。同步盘会在后台改文件时间、锁文件解压时容易缺文件后面查 404 会查到怀疑人生。放到本地固定路径比如 Linux 下/srv/docs/python-3.13-zhWindows 下D:\docs\python-3.13-zh路径里不要有中文和空格。3. 下载与落盘校验、解压和路径权限的三道关3.1 获取压缩包后先做哈希校验拿到压缩包后我第一件事不是解压而是校验。离线文档包经常在群里、U 盘、内网文件服务器之间转手坏包不一定报错解压到一半才提示 CRC 错误或者少几个_static文件页面样式和搜索全废。发布方一般会同时给一个.sha256或.md5校验文件没有的话至少核对文件大小和来源。Linux 下这样校验# 进入压缩包所在目录文件名以你实际拿到的为准 cd /opt/src # 生成 SHA256 并人工比对发布方给出的值 sha256sum python-3.13-docs-zh-cn-html.zip # 如果发布方给了 .sha256 文件直接校验 sha256sum -c python-3.13-docs-zh-cn-html.zip.sha256sha256sum只做一件事把文件内容算成一串摘要。-c参数会读取校验文件里记录的文件名和摘要逐项比对。这里最容易错的是文件名不一致校验文件里写的是python-3.13-docs-zh-cn-html.zip你本地改名成python313中文文档.zip-c就会报“没有那个文件”。要么改回原名要么手动比对摘要值。Windows 下没有sha256sum用系统自带的:: 在压缩包所在目录打开命令提示符路径换成实际文件 certutil -hashfile python-3.13-docs-zh-cn-html.zip SHA256输出是一串十六进制摘要和发布方给的值逐位比对。不要只比对前几位也不要忽略大小写以外的差异。校验不通过就重新拿包别抱着“也许能解压”的心态往下走后面排查 404 的时间远比重新下载长。3.2 解压前先用 -l 看顶层目录校验通过后先看压缩包里面的目录结构不要直接unzip到当前目录。很多包顶层自带一层python-3.13-docs-zh-cn-html/你解压到/srv/docs/python-3.13-zh后真实首页会变成/srv/docs/python-3.13-zh/python-3.13-docs-zh-cn-html/index.html。Nginx 的root如果只指到前一层首页打不开指到后一层又容易把路径写死换版本时全要改。先列目录# 不解压只看压缩包内前 30 行文件列表 unzip -l python-3.13-docs-zh-cn-html.zip | head -n 30 # 如果是 tar.gz 包这样看 tar -tzf python-3.13-docs-zh-cn-html.tar.gz | head -n 30unzip -l只列内容不改磁盘head -n 30限制输出行数避免刷屏。看的时候重点找index.html前面有几层目录。如果列表里直接就是index.html、library/、_static/说明包内没有多余顶层如果前面还有一层目录解压后要么进那一层再启动服务要么用--strip-components去掉一层。确认后解压到固定路径# 创建站点目录路径不要带中文和空格 sudo mkdir -p /srv/docs/python-3.13-zh # 解压到站点目录如果包内自带顶层目录这里会多一层后面用 find 确认 sudo unzip -q python-3.13-docs-zh-cn-html.zip -d /srv/docs/python-3.13-zh # 找到真正的 index.html确认层级 find /srv/docs/python-3.13-zh -maxdepth 3 -name index.html-d指定解压目标目录-q安静模式不逐条打印文件。解压完用find找index.html输出结果就是你要在 Nginx 里配置的root目录。比如输出是/srv/docs/python-3.13-zh/index.htmlroot就写/srv/docs/python-3.13-zh如果输出是/srv/docs/python-3.13-zh/python-3.13-docs-zh-cn-html/index.html要么把root指到后面那层要么把内容整体上移一层。我一般选择后者路径短换版本时只改目录名。3.3 路径与权限别把文档放在桌面和中文目录路径这件事看起来不重要实际最容易埋雷。放在桌面、下载目录、中文名文件夹、带空格的项目目录都会在不同环节出问题http.server启动时路径解析失败Nginx 的root里空格要转义浏览器 URL 里中文被编码后子页面 404。更麻烦的是有些解压工具对中文路径处理不一致解压出来的文件名可能变成乱码后面查页面时怎么都对不上。我一般用这套路径Linux: /srv/docs/python-3.13-zh Windows: D:\docs\python-3.13-zh macOS: /Users/Shared/docs/python-3.13-zh目录确定后配权限。静态文档只需要读不需要写。Linux 下建议属主root属组给运行 Web 服务的账户目录 755文件 644# 创建一个只跑静态服务的系统账户已存在就跳过 sudo useradd -r -s /usr/sbin/nologin docsvc 2/dev/null || true # 属主 root属组 docsvc目录可进入文件可读 sudo chown -R root:docsvc /srv/docs/python-3.13-zh sudo find /srv/docs/python-3.13-zh -type d -exec chmod 755 {} \; sudo find /srv/docs/python-3.13-zh -type f -exec chmod 644 {} \;useradd -r建系统账户-s /usr/sbin/nologin禁止登录只用来跑服务。chown -R递归改属主属组find -type d -exec chmod 755只给目录加执行位find -type f -exec chmod 644让文件可读不可写。不要图省事chmod -R 777静态站点一旦可写被人塞进脚本就不是文档站的事了。如果机器开了 SELinux光改权限还不够Nginx 读/srv下的文件可能返回 403。先确认状态# 查看 SELinux 是否 enforcing getenforce # 如果是 Enforcing给文档目录打 httpd 可读标签 sudo chcon -R -t httpd_sys_content_t /srv/docs/python-3.13-zhgetenforce返回Enforcing才需要处理chcon是临时改上下文重启或重新打标签后可能失效。长期方案是用semanage fcontext加restorecon但多数内网文档站用chcon先跑通后面再补策略。这个坑在第 5 章还会展开。4. 本地部署python -m http.server 临时跑与 Nginx 稳定跑4.1 先定位 index.html 的真实层级启动服务前先站到index.html所在目录或者拿到它的绝对路径。后面不管用http.server还是 Nginx都是围绕这个目录转。可以用两条命令确认# 找到 index.html 的绝对路径 find /srv/docs/python-3.13-zh -maxdepth 3 -name index.html # 进入它所在目录确认 library 和 search.html 也在同一层 cd /srv/docs/python-3.13-zh ls -1 index.html search.html library reference _static 2/dev/null如果library、_static不在这里说明进错层了。search.html不在同一层搜索入口就会 404。确认后记下这个绝对路径后面--directory和 Nginxroot都用它。4.2 临时方案http.server 的端口、绑定地址与目录参数自己本机查文档最快的是 Python 自带的http.server。不用装 Nginx不用改配置一条命令起一个静态文件服务。Python 3.13 的http.server支持--bind、--port、--directory参数我一般这样起# 用 Python 3.13 在 8013 端口起服务只监听本机回环地址 python3.13 -m http.server 8013 \ --bind 127.0.0.1 \ --directory /srv/docs/python-3.13-zh8013是端口避开常用的 8000免得和别的调试服务撞车。--bind 127.0.0.1表示只允许本机访问别人连不进来要给同组内网访问改成--bind 0.0.0.0同时确认防火墙放行。--directory直接指定文档根目录不用先cd路径写绝对路径最稳。启动后浏览器打开http://127.0.0.1:8013/。这个方案适合临时查不适合长期跑终端一关服务就停没有访问日志轮转没有缓存控制并发高了也吃力。Windows 下把python3.13换成py -3.13路径换成D:\docs\python-3.13-zh:: Windows 下用 py 启动器指定 3.13监听本机 8013 py -3.13 -m http.server 8013 --bind 127.0.0.1 --directory D:\docs\python-3.13-zh如果启动时报Address already in use说明端口被占换一个端口比如8014。不要直接杀进程先确认占用者是不是你自己的旧服务# Linux 下查看 8013 端口被谁占用 ss -ltnp | grep 8013ss -ltnp列出监听中的 TCP 端口grep过滤目标端口。看到旧进程再决定是停掉还是换端口。4.3 稳定方案Nginx 静态站点、UTF-8 与缓存配置要给多人用或者要开机自启我一般上 Nginx。配置不复杂关键是root指对、编码指对、缓存别乱加。下面是一份够用的站点配置server { listen 80; server_name docs.local; # 必须指向 index.html 所在目录不要多一层也不要少一层 root /srv/docs/python-3.13-zh; index index.html; # 中文文档必须显式声明 UTF-8否则部分浏览器会按 ISO-8859-1 猜 charset utf-8; location / { try_files $uri $uri/ 404; } # 静态资源缓存 7 天减少重复加载 CSS/JS/字体 location ~* \.(js|css|png|svg|woff2)$ { expires 7d; add_header Cache-Control public; } # 搜索页不缓存避免索引更新后仍拿旧页面 location /search.html { add_header Cache-Control no-store; } }listen 80是监听端口内网没有域名就先用 IP 访问server_name docs.local是示例域名没有 DNS 可以写_或机器 IP。root后面不要带index.html只写到目录。charset utf-8影响响应头里的Content-Type中文页面乱码时先查这里。try_files先找文件再找目录都没有才 404避免把/library/这类目录请求直接判死。静态资源缓存 7 天够用search.html单独no-store是为了搜索索引更新后不拿旧缓存。配置写完后先测语法再重载# 测试 Nginx 配置语法 sudo nginx -t # 语法通过后平滑重载 sudo systemctl reload nginxnginx -t会告诉你配置文件哪一行有语法错误不要跳过直接 reload。reload是平滑重载不会断开现有连接如果服务没启动用systemctl start nginx。4.4 常驻运行systemd 单元与 Windows 计划任务http.server临时跑可以但机器重启就没了。Linux 下用 systemd 管起来比nohup稳[Unit] DescriptionPython 3.13 Chinese offline docs Afternetwork.target [Service] Typesimple Userdocsvc WorkingDirectory/srv/docs/python-3.13-zh ExecStart/usr/bin/python3.13 -m http.server 8013 --bind 127.0.0.1 Restarton-failure NoNewPrivilegestrue PrivateTmptrue [Install] WantedBymulti-user.targetUserdocsvc是运行账户必须对文档目录有读权限WorkingDirectory指定工作目录ExecStart里的 Python 路径要用which python3.13确认真实位置有的机器装在/usr/local/bin/python3.13写/usr/bin会启动失败。Restarton-failure让异常退出后自动拉起NoNewPrivileges和PrivateTmp是基本的收窄权限。保存为/etc/systemd/system/python313-docs.service然后# 重新加载 unit 文件设置开机自启并立即启动 sudo systemctl daemon-reload sudo systemctl enable --now python313-docs.service # 查看状态和最近日志 systemctl status python313-docs.service --no-pager journalctl -u python313-docs.service -n 50 --no-pagerdaemon-reload让 systemd 重新读 unit 文件enable --now同时做开机自启和立即启动。status看是否active (running)journalctl -n 50看最近 50 行日志。如果启动失败先看ExecStart路径和User权限这两个占多数。Windows 下不想装 Nginx可以用“任务计划程序”建一个开机任务程序填py参数填-3.13 -m http.server 8013 --bind 127.0.0.1 --directory D:\docs\python-3.13-zh起始于填D:\docs。任务要勾选“不管用户是否登录都要运行”否则注销后服务就停。这个方案能用但日志和权限控制不如 Nginx长期给团队用还是建议上 Nginx。5. 常见问题排查离线文档搜索失效、404 与 403 的 5 个坑5.1 坑一双击 index.html 后搜索框没反应现象页面能正常打开侧边栏也能点但在搜索框输入pathlib后没结果或者搜索页一直转圈。按 F12 看控制台通常能看到加载searchindex.js失败或者XMLHttpRequest被拦截。原因浏览器对file://协议有同源限制search.html去加载同目录的searchindex.js时被当成跨域请求拦掉。这不是文档包缺文件也不是浏览器坏了是打开方式不对。Python 文档的搜索依赖 JS 索引不是纯静态链接必须通过 HTTP 访问。解决不要双击index.html。用python3.13 -m http.server起一个本地服务或者用 Nginx 配静态站点然后通过http://127.0.0.1:8013/访问。已经起了服务还是搜不到先看search.html是否返回 200再看searchindex.js是否 404# 检查搜索页和索引文件是否都能正常返回 curl -I http://127.0.0.1:8013/search.html curl -I http://127.0.0.1:8013/searchindex.js两个都应该是200 OK。如果searchindex.js是 404说明解压不完整或者路径层级不对回到第 3 章重新确认index.html所在目录。5.2 坑二路径带中文或空格首页能开子页面 404现象首页http://127.0.0.1:8013/能打开点“标准库”就 404地址栏里出现一长串%E4%B8%AD%E6%96%87。Nginx 日志里能看到请求路径被拆成两段或者返回 400。原因文档目录放在中文名或带空格的路径下比如/home/用户/桌面/Python 3.13 文档/。http.server和 Nginx 对 URL 编码、空格转义的处理不完全一致子页面链接里的相对路径一旦带上空格或中文就容易解析失败。有些解压工具还会把中文文件名解成乱码问题更隐蔽。解决把文档整体移到纯英文、无空格路径比如/srv/docs/python-3.13-zh或D:\docs\python-3.13-zh。移动后重新确认index.html层级重启服务。不要试图在 Nginx 里用rewrite硬修中文路径修好一个页面还会有下一个。路径规范是这类静态站点的地基地基歪了后面全是补丁。5.3 坑三端口被占用或防火墙拦截现象http.server启动时报OSError: [Errno 98] Address already in use或者本机能打开同组同事访问http://你的IP:8013/一直转圈。Nginx 场景下则是本机curl通外部浏览器打不开。原因端口被旧服务占用或者--bind 127.0.0.1只监听了回环地址外部根本连不进来还有一层是防火墙没放行端口。Nginx 场景下还要看listen是不是只写了127.0.0.1:80。解决先查端口占用再查监听地址最后查防火墙。Linux 下# 查端口占用 ss -ltnp | grep 8013 # 查防火墙放行端口firewalld 示例 sudo firewall-cmd --list-ports sudo firewall-cmd --add-port8013/tcp --permanent sudo firewall-cmd --reload如果是http.server要给外部访问把--bind 127.0.0.1改成--bind 0.0.0.0如果前面套了 Nginxhttp.server继续保持只监听127.0.0.1由 Nginx 对外。不要在没搞清监听地址前就去改防火墙方向容易反。5.4 坑四解压多了一层目录Nginx 首页正常但库页面全 404现象访问http://docs.local/能看到首页点library/pathlib.html返回 404。nginx -t没报错root看起来也没写错。find一下发现index.html在/srv/docs/python-3.13-zh/python-3.13-docs-zh-cn-html/index.html。原因压缩包顶层自带一层目录解压时没注意Nginx 的root指到了外层。首页能开是因为 Nginx 的index指令在子目录里找到了index.html不更常见的是你访问的首页其实是目录列表或另一个入口子页面相对链接按外层解析自然全 404。这类问题最迷惑的地方是“首页看起来正常”让人误以为路径没问题。解决用find找到真实index.html把 Nginxroot指到它所在目录或者把内容整体上移一层# 确认真实层级 find /srv/docs/python-3.13-zh -maxdepth 3 -name index.html # 如果多了一层把内层内容移到外层先确认外层没有重要文件 sudo mv /srv/docs/python-3.13-zh/python-3.13-docs-zh-cn-html/* /srv/docs/python-3.13-zh/ sudo rmdir /srv/docs/python-3.13-zh/python-3.13-docs-zh-cn-html移动后重新nginx -t并reload。如果不想移动文件就把root改成内层绝对路径但换版本时记得同步改别把旧路径留在配置里。5.5 坑五SELinux 或文件权限导致 403现象curl -I http://docs.local/返回403 ForbiddenNginx 错误日志里写Permission denied。文件明明存在ls -l看权限也不低甚至试过chmod 777还是 403。原因两个层面。第一是普通权限Nginx worker 账户对目录没有执行位或对文件没有读权限第二是 SELinux目录上下文不是httpd_sys_content_t即使权限全开也会被拦。chmod 777只解决第一层解决不了 SELinux 标签。解决先看 Nginx 错误日志定位是哪个路径再分别查权限和 SELinux# 看 Nginx 错误日志最后 30 行 sudo tail -n 30 /var/log/nginx/error.log # 查目录权限和 SELinux 上下文 ls -ld /srv/docs/python-3.13-zh ls -Z /srv/docs/python-3.13-zh | head # 如果 SELinux 是 Enforcing补上下文 getenforce sudo chcon -R -t httpd_sys_content_t /srv/docs/python-3.13-zh权限按第 3 章给的 755/644 配属组要让 Nginx worker 能读。SELinux 用chcon先跑通长期用semanage fcontext -a -t httpd_sys_content_t /srv/docs/python-3.13-zh(/.*)?加restorecon -Rv固化。不要一上来就setenforce 0关掉 SELinux 只是把问题藏起来换台机器还会复现。6. 装完怎么验证从 curl 状态码到断网搜索的验收清单装完别只看首页能不能开按下面这套走一遍能省掉后面很多“时好时坏”的麻烦。先跑三条命令# 1. 首页状态码和内容类型 curl -I http://127.0.0.1:8013/ # 2. 标准库子页面是否可达 curl -I http://127.0.0.1:8013/library/pathlib.html # 3. 搜索索引是否加载得到 curl -I http://127.0.0.1:8013/searchindex.js三个都应该是200 OK首页的Content-Type里最好带text/html; charsetutf-8。如果首页 200、子页面 404回到第 5.4 节查目录层级如果searchindex.js404查解压完整性和文件名大小写。再用浏览器做断网验收验收项操作通过标准首页打开http://127.0.0.1:8013/标题和导航正常样式不丢搜索搜索pathlib或asyncio出现结果列表点击能进页面子页面点进library/pathlib.html正文和侧边栏都正常断网关闭 Wi-Fi 或拔网线后刷新页面和搜索仍可用移动端手机连同一内网访问页面不横向溢出搜索可用最后看服务日志有没有持续报错http.server看终端输出Nginx 看access.log和error.log。如果都通过这套 Python 3.13 中文离线 HTML 文档就算真正落地了。我以前图省事解压完双击index.html就开始查结果搜索用不了还以为是文档包缺文件重新下载了两遍。从那以后我每次装离线文档都强制走一遍“起 HTTP 服务、curl 三个地址、断网搜一次”的流程不再靠双击碰运气。希望帮到你。本文还有配套的精品资源点击获取