企业官网建设流程全解析

简介：这份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 生成的结构，根目录下一般能看到这些入口：

这里最关键的是search.html和searchindex.js。搜索不是简单的页面内跳转，它要加载索引文件，浏览器在file://协议下会限制这类请求，所以双击打开时“页面能看、搜索没反应”几乎必现。另一个关键是_static/，如果 Nginx 权限没配好，HTML 能返回，但 CSS 和 JS 全是 403，页面会变成纯文本堆叠，看起来像文档包坏了。

提示：解压后先用find确认index.html的真实层级。有些压缩包顶层自带一个目录，root指错一层，首页能开，子页面全 404。

2.3 运行环境清单：浏览器、解压工具与 Web 服务器怎么选

这套东西对机器要求不高，但几个组件不能缺。下面是我一般会先对一遍的清单：

如果只是自己本机查，python -m http.server足够，不用装 Nginx。要给小组内网共用，或者要开机自启，Nginx 更稳：它能配 UTF-8、缓存、访问日志，也能把文档站和别的服务隔开。Windows 上不想装 Nginx，也可以用 Python 起服务后配计划任务，但别用“双击 bat 窗口一直开着”这种办法，机器一重启就没了。

还有一点：不要把文档包放在同步盘目录里。同步盘会在后台改文件时间、锁文件，解压时容易缺文件，后面查 404 会查到怀疑人生。放到本地固定路径，比如 Linux 下/srv/docs/python-3.13-zh，Windows 下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.sha256

sha256sum只做一件事：把文件内容算成一串摘要。-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 30

unzip -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.html，root就写/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-zh

getenforce返回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-zh

8013是端口，避开常用的 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 8013

ss -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 nginx

nginx -t会告诉你配置文件哪一行有语法错误，不要跳过直接 reload。reload是平滑重载，不会断开现有连接；如果服务没启动，用systemctl start nginx。

4.4 常驻运行：systemd 单元与 Windows 计划任务

http.server临时跑可以，但机器重启就没了。Linux 下用 systemd 管起来，比nohup稳：

[Unit] Description=Python 3.13 Chinese offline docs After=network.target [Service] Type=simple User=docsvc WorkingDirectory=/srv/docs/python-3.13-zh ExecStart=/usr/bin/python3.13 -m http.server 8013 --bind 127.0.0.1 Restart=on-failure NoNewPrivileges=true PrivateTmp=true [Install] WantedBy=multi-user.target

User=docsvc是运行账户，必须对文档目录有读权限；WorkingDirectory指定工作目录；ExecStart里的 Python 路径要用which python3.13确认真实位置，有的机器装在/usr/local/bin/python3.13，写/usr/bin会启动失败。Restart=on-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-pager

daemon-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-port=8013/tcp --permanent sudo firewall-cmd --reload

如果是http.server要给外部访问，把--bind 127.0.0.1改成--bind 0.0.0.0；如果前面套了 Nginx，http.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 Forbidden，Nginx 错误日志里写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; charset=utf-8。如果首页 200、子页面 404，回到第 5.4 节查目录层级；如果searchindex.js404，查解压完整性和文件名大小写。

再用浏览器做断网验收：

最后看服务日志有没有持续报错：http.server看终端输出，Nginx 看access.log和error.log。如果都通过，这套 Python 3.13 中文离线 HTML 文档就算真正落地了。

我以前图省事，解压完双击index.html就开始查，结果搜索用不了，还以为是文档包缺文件，重新下载了两遍。从那以后我每次装离线文档，都强制走一遍“起 HTTP 服务、curl 三个地址、断网搜一次”的流程，不再靠双击碰运气。希望帮到你。

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