Python内置开发服务器http.server的大用处

一行命令，把当前目录变成网站。

为什么需要它？

你是否有过这样的经历：

• 写了一个 HTML 页面，双击打开，却发现 fetch 本地 JSON 报跨域错误；
• 想给同事/手机快速传几个文件，却没有现成的共享工具；
• 只想快速预览一下前端构建产物，又不想装 Nginx 或开 IDE 插件。

Python 自带的 http.server 模块就是为此而生的：一个零依赖、零配置的静态文件开发服务器，一条命令就能把任意目录变成可访问的网站。它非常适合本地开发调试、临时文件共享和快速原型预览。

⚠️ 先说结论：它只适合开发和临时场景，不能用于生产环境。 原因后面会详细讲。

快速上手

在终端进入你的静态文件目录，执行：

python -m http.server

然后浏览器访问：

http://127.0.0.1:8000

就这么简单。你会看到一个自动生成的目录列表页，点击即可浏览和下载文件。

指定端口：

python -m http.server 8080

停止服务：按 Ctrl + C。

小知识：Python 2 时代这个模块叫 SimpleHTTPServer，Python 3 整合进了 http.server，用法从 python -m SimpleHTTPServer 变成了 python -m http.server。

常用命令行参数

两个最实用的组合：

# 只允许本机访问（更安全）
python -m http.server --bind 127.0.0.1

# 服务指定目录，而不必先 cd 进去
python -m http.server -d ./frontend/dist

典型应用场景

1. 本地预览前端页面，避开 file:// 跨域问题

直接双击 HTML 文件时，浏览器以 file:// 协议打开，fetch、XMLHttpRequest 等请求会因为跨域被拦截（读取本地 JSON 经常报错）。用 http.server 启动后，页面通过 http://127.0.0.1:8000 访问，走正常 HTTP 协议，前端调试顺畅很多。

2. 局域网临时文件共享

# 默认就绑定所有网卡，同一局域网内的人可以通过你的 IP 访问
python -m http.server 8000

别人在浏览器打开 http://你的IP:8000 即可浏览、下载你当前目录的文件。手机传文件到电脑、同事之间快速交换文件都很方便。

查看本机局域网 IP：Linux/macOS 用 ip addr 或 ifconfig，Windows 用 ipconfig。

3. 快速预览构建产物

前端项目构建后，用一条命令预览 dist 目录，不用装任何工具：

python -m http.server -d dist

4. 自动化测试中的静态资源服务

在 CI、Selenium、Playwright 等测试场景中，经常需要一个临时的静态服务来承载测试页面，http.server 是最轻量的选择。

5. 快速演示原型

给客户或同事演示一个纯静态原型，不需要配置任何服务器环境，开箱即用。

进阶：用 Python 代码定制

命令行版其实只是内置 HTTPServer + SimpleHTTPRequestHandler 的封装。想定制行为，直接写代码即可。

最基本的代码方式

from http.server import HTTPServer, SimpleHTTPRequestHandler

server = HTTPServer(("0.0.0.0", 8000), SimpleHTTPRequestHandler)
print("serving at http://127.0.0.1:8000")
server.serve_forever()

解决单线程阻塞：ThreadingHTTPServer

默认的 HTTPServer 是单线程的，一次只能处理一个请求，遇到慢客户端会阻塞后面的请求。用线程版（Python 3.7+）可以并发处理：

from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler

ThreadingHTTPServer(("0.0.0.0", 8000), SimpleHTTPRequestHandler).serve_forever()

给响应加上 CORS 头，解决跨域调试

前端开发经常遇到跨域问题，自定义一个 Handler 加上响应头即可：

from http.server import HTTPServer, SimpleHTTPRequestHandler

class CORSRequestHandler(SimpleHTTPRequestHandler):
    def end_headers(self):
        self.send_header("Access-Control-Allow-Origin", "*")
        super().end_headers()

HTTPServer(("127.0.0.1", 8000), CORSRequestHandler).serve_forever()

自定义文件类型映射

默认的 MIME 表可能不认识 .wasm、.mjs 等新格式，导致浏览器按错误类型解析：

import mimetypes
from http.server import HTTPServer, SimpleHTTPRequestHandler

class CustomHandler(SimpleHTTPRequestHandler):
    extensions_map = SimpleHTTPRequestHandler.extensions_map.copy()
    extensions_map.update({
        ".wasm": "application/wasm",
        ".mjs": "application/javascript",
    })

HTTPServer(("127.0.0.1", 8000), CustomHandler).serve_forever()

开启 HTTPS（本地自签名）

import ssl
from http.server import HTTPServer, SimpleHTTPRequestHandler

httpd = HTTPServer(("0.0.0.0", 8443), SimpleHTTPRequestHandler)
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ctx.load_cert_chain("cert.pem", "key.pem")  # 需要自己生成证书
httpd.socket = ctx.wrap_socket(httpd.socket, server_side=True)
httpd.serve_forever()

与其他开发服务器的对比

一句话区分：

• http.server：Python 自带，纯静态文件，无后端逻辑，零依赖开箱即用；
• Django runserver / flask run：框架的开发服务器，能跑后端代码、连数据库，但必须先有框架项目；
• live-server / Vite：前端开发体验更好（自动刷新、模块热更新），但要装 Node 生态；
• Nginx：生产环境的主角，功能强大，但不是"开发服务器"。

避坑指南

1. 不要上生产：默认单线程、无并发优化、无身份认证、无 HTTPS、无访问控制，遇到并发基本会卡死，也没有安全防护能力。生产请用 Nginx、Caddy 等。

2. 注意暴露风险：默认绑定 0.0.0.0，意味着局域网内任何人都能访问并下载你当前目录下的所有文件（包括配置、密钥等敏感文件）。在不受信任的网络中，务必加 --bind 127.0.0.1，并且不要在敏感目录启动它。

3. 目录遍历是特性也是风险：服务会把整个目录结构暴露出来，这是文件共享功能的基础，但也意味着"暴露什么目录=暴露什么文件"，请谨慎选择启动目录。

4. 不处理动态逻辑：它只做静态文件服务，表单提交、数据库操作、API 路由都不支持。需要后端逻辑请用 Django、Flask、FastAPI 等框架。

5. 中文/特殊字符文件名：浏览器访问时一般会自动进行 URL 编码，但个别场景（如直接在 URL 里手输中文路径）可能出现编码不一致的问题，项目内尽量使用规范的命名。

6. CGI 已被移除：如果你是从旧教程里看到 --cgi 参数，注意 Python 3.13 起该功能已被移除，不要再依赖它。

总结

• 是什么：Python 内置的轻量静态文件开发服务器，零依赖、一条命令启动。
• 能做什么：本地预览前端页面、局域网文件共享、快速展示静态原型、测试环境临时托管。
• 不能做什么：跑后端逻辑、承担生产流量、提供安全保障。
• 记住两个命令： bash python -m http.server # 当前目录，默认 8000 端口 python -m http.server -d dist --bind 127.0.0.1 # 指定目录，仅本机访问

它是开发者的"瑞士军刀"——不精致，但足够快、足够轻，在你只需要一个静态服务器的时候，永远是最省事的那个。