也许你不需要创建.venv, 此规范使python脚本自备依赖

在 Python 开发中，我们经常陷入一种“环境通胀”：为了运行一个不到 50 行的简单脚本（比如抓个接口数据、写个 Streamlit 演示），却不得不经历 python -m venv .venv、激活环境、pip install 等一系列繁琐动作。

如果你手头有十个这样的脚本，你的磁盘就会被几十个重复的 .venv 文件夹占满。Astral 推出的 uv 工具正在终结这种低效。 配合 PEP 723 (Inline script metadata) 规范，我们可以真正实现“单文件即项目”的优雅体验。

1. 核心纠偏：uv init 还是 uv venv？

很多初学者在刚接触 uv 时会感到困惑。其实，针对不同的颗粒度，uv 提供了三条清晰的路径：

2. 现代方案：PEP 723 脚本元数据

PEP 723 是 Python 社区的一个里程碑。它允许我们将依赖信息直接以“代码注释”的形式嵌入到脚本头部。这意味着你的脚本具备了自描述性——它是自给自足的。

规范示例

当你运行一个包含以下代码块的脚本时：

# /// script
# dependencies = [
#   "httpx",
#   "streamlit",
# ]
# ///

import httpx
import streamlit as st

st.title("Token 刷新工具")
# 脚本逻辑...

为什么这种方式更优秀？

1. 环境全自动化：运行 uv run script.py 时，uv 会瞬时在后台创建临时环境。如果依赖没变，下次运行会直接秒开。
2. 零污染：它不会在你的脚本目录下留下 .venv 文件夹，全局环境永远保持洁净。
3. 极简分发：把脚本发给同事时，不用再附带 requirements.txt。对方只要装了 uv，直接运行即可。

3. 实战技巧：如何快速配置

不想手动打那堆 # /// 注释？uv 早就帮你想好了自动化方案。

如果你已经写好了一个脚本 refresh_token.py，只需在终端输入：

# 为脚本一键添加依赖声明
uv add --script refresh_token.py "streamlit" "httpx"

这会自动在文件头插入符合 PEP 723 规范的元数据。之后，你只需一行命令即可启动：

uv run refresh_token.py

4. 进阶特性：精细化控制

除了基础的依赖管理，你还可以在脚本头部玩出更多花样：

• 版本约束："requests>=2.31.0"，确保脚本不会因为库升级而崩掉。
• 指定 Python 版本：# requires-python = ">=3.12"，自动调用合适的解释器。
• 工具链配置：通过 [tool.uv] 块自定义镜像源，解决国内下载慢的问题。

结论与行动建议

Python 脚本的开发模式正在从“手动建档”转向“声明式运行”。

• 立即可做：安装 uv，并尝试用 uv run --with <库名> <脚本> 运行一个临时脚本。
• 长期实践：对于所有的工具类脚本，统一使用 uv add --script 写入元数据，把每一个脚本都打造成一个自给自足的“单兵作战单元”。