在 Python 开发中，我们经常陷入一种"环境通胀"：为了运行一个不到 50 行的简单脚本（比如抓个接口数据、写个 Streamlit 演示），却不得不经历 python -m venv .venv、激活环境、pip install 等一系列繁琐动作。
如果你手头有十个这样的脚本，你的磁盘就会被几十个重复的 .venv 文件夹占满。Astral 推出的 uv 工具正在终结这种低效。 配合 PEP 723 (Inline script metadata) 规范，我们可以真正实现"单文件即项目"的优雅体验。
1. 核心纠偏：uv init 还是 uv venv？
很多初学者在刚接触 uv 时会感到困惑。其实，针对不同的颗粒度，uv 提供了三条清晰的路径：
| 命令 | 适用场景 | 产物 |
|---|---|---|
uv init |
正规军：需要长期维护、多人协作的复杂应用。 | pyproject.toml, .python-version |
uv venv |
传统派 ：只是想快点创建环境，继续用传统的 pip 习惯。 |
.venv 文件夹 |
uv run |
特种兵 ：单脚本运行，不产生任何本地依赖文件夹。 | 临时缓存环境（自动管理） |
!TIP 对于简单的工具脚本，忘掉前两个命令 。你只需要
uv run。
2. 现代方案：PEP 723 脚本元数据
PEP 723 是 Python 社区的一个里程碑。它允许我们将依赖信息直接以"代码注释"的形式嵌入到脚本头部。这意味着你的脚本具备了自描述性------它是自给自足的。
规范示例
当你运行一个包含以下代码块的脚本时：
python
# /// script
# dependencies = [
# "httpx",
# "streamlit",
# ]
# ///
import httpx
import streamlit as st
st.title("Token 刷新工具")
# 脚本逻辑...为什么这种方式更优秀？
- 环境全自动化 ：运行
uv run script.py时，uv会瞬时在后台创建临时环境。如果依赖没变，下次运行会直接秒开。 - 零污染 ：它不会在你的脚本目录下留下
.venv文件夹，全局环境永远保持洁净。 - 极简分发 ：把脚本发给同事时，不用再附带
requirements.txt。对方只要装了uv，直接运行即可。
3. 实战技巧：如何快速配置
不想手动打那堆 # /// 注释？uv 早就帮你想好了自动化方案。
如果你已经写好了一个脚本 refresh_token.py，只需在终端输入：
bash
# 为脚本一键添加依赖声明
uv add --script refresh_token.py "streamlit" "httpx"这会自动在文件头插入符合 PEP 723 规范的元数据。之后，你只需一行命令即可启动：
bash
uv run refresh_token.py4. 进阶特性：精细化控制
除了基础的依赖管理，你还可以在脚本头部玩出更多花样：
- 版本约束 ：
"requests>=2.31.0"，确保脚本不会因为库升级而崩掉。 - 指定 Python 版本 ：
# requires-python = ">=3.12"，自动调用合适的解释器。 - 工具链配置 ：通过
[tool.uv]块自定义镜像源，解决国内下载慢的问题。
结论与行动建议
Python 脚本的开发模式正在从"手动建档"转向"声明式运行"。
- 立即可做 ：安装 uv，并尝试用
uv run --with <库名> <脚本>运行一个临时脚本。 - 长期实践 ：对于所有的工具类脚本，统一使用
uv add --script写入元数据，把每一个脚本都打造成一个自给自足的"单兵作战单元"。