0.1 环境搭建与运行

概述

作为前端开发者，你已经非常熟悉 Node.js 的工作流：安装 Node、用 npm 装依赖、node index.js 跑代码、node_modules 里放依赖。Python 有一套几乎一一对应的概念，只是名字不同、组织方式略有差异。这一章帮你在 30 分钟内把 Python 环境搭起来，并理解它和 Node 生态的对应关系。

JS/TS ↔ Python 对照表

概念	Node.js / 前端生态	Python 生态	说明
运行时 / 引擎	V8 引擎（跑 JS）	CPython 解释器（跑 Python）	都是"执行你代码的东西"，只是实现语言不同
安装运行时	下载 Node 安装包 / nvm	下载 Python 安装包 / pyenv	都可以直接装二进制或版本管理工具
版本管理	nvm / fnm / Volta	pyenv / uv 自带	切换不同版本的语言
包管理器	npm / yarn / pnpm	pip / uv	安装第三方依赖
包注册中心	npm registry (registry.npmjs.org)	PyPI (pypi.org)	官方公共源
项目配置文件	package.json	pyproject.toml	项目元信息与依赖声明
依赖锁文件	package-lock.json / yarn.lock	uv.lock / poetry.lock / requirements.txt	锁定精确版本
依赖安装目录	node_modules/	venv（虚拟环境，通常在 .venv/）	本地隔离依赖
运行脚本	node index.js	python main.py	执行一个文件
交互式控制台	node（无参数直接进入）	python（无参数直接进入）	REPL
脚本入口管理	scripts 字段 + npm run	没有官方等价物，常用 task runner 或 make	见下文
全局安装 CLI	npm install -g	pipx	隔离安装命令行工具
发布包	npm publish	`uv publish` / `python -m build` + twine	发布到 PyPI
包名规范	通常驼峰或短横线	全小写 + 下划线	`my-tool` → `my_tool`
入口函数约定	`main()` / `exports`	`if __name__ == "__main__":`	模块入口守卫

核心概念

1. 解释器 CPython vs JS 引擎 V8

你已经知道：JS 代码由 V8（或 SpiderMonkey、JavaScriptCore）执行。Python 同理，代码由 CPython（用 C 语言写的官方解释器）执行。

官方版本就叫 CPython（绝大多数人说的"Python"就是它）。
也有其他实现：PyPy（JIT 加速）、Jython（跑在 JVM 上）、GraalPy 等，但日常用 CPython 即可。
类比：V8 是 JS 的一个引擎，CPython 是 Python 的一个解释器。都遵循各自的语言规范（ECMAScript ↔ Python 语言参考）。

2. 包管理器 pip/uv vs npm

pip 是 Python 官方随附的包管理器，作用等价于 npm install。

npm 命令	pip 命令	uv 命令（现代推荐）
`npm install`	`pip install -r requirements.txt`	`uv sync`
`npm install lodash`	`pip install requests`	`uv add requests`
`npm uninstall lodash`	`pip uninstall requests`	`uv remove requests`
`npm install -g`	`pipx install`	`uv tool install`
`npm list`	`pip list`	`uv pip list`
`npm update`	`pip install -U`	`uv lock --upgrade`

uv 是近两年崛起的、用 Rust 写的极速包管理器，定位类似前端的 pnpm（快、省空间、有锁文件）。强烈推荐新项目直接用 uv。

3. 虚拟环境 venv vs node_modules

你已经习惯：npm install 把依赖装到当前项目的 node_modules/，每个项目互相隔离。

Python 的隔离机制叫虚拟环境（virtual environment）：

用 python -m venv .venv 创建一个独立的解释器副本 + 依赖目录。
激活后，pip install 只会装到这个环境里，不影响全局或其他项目。
类比：node_modules/ 是"项目的依赖文件夹"，venv 是"项目的独立解释器 + 依赖文件夹"。Python 多了一层"连解释器本身也隔离"，因为 Python 依赖更依赖全局 site-packages。

# Node 思维
npm install          # 依赖进 node_modules/

# Python 思维（先建环境再装）
python -m venv .venv         # 创建虚拟环境（类似"初始化 node_modules 隔离区"）
.venv\Scripts\activate       # Windows 激活；macOS/Linux 用 source .venv/bin/activate
pip install requests         # 依赖进 .venv/

用 uv 可以省掉手动激活这一步：uv sync 自动建 .venv 并装依赖，uv run python main.py 自动在虚拟环境里运行。

4. pyproject.toml vs package.json

pyproject.toml 是 Python 项目的事实标准配置文件，相当于 package.json：

# pyproject.toml
[project]
name = "my-app"
version = "0.1.0"
description = "一个示例项目"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31",
    "pydantic>=2.0",
]

[project.optional-dependencies]  # 类似 devDependencies
dev = ["pytest", "ruff"]

[dependency-groups]              # uv 的 dev 依赖组
dev = ["pytest>=8"]

对应 package.json 里的 dependencies 与 devDependencies。注意 Python 用 >= 表示版本范围，而 npm 用 ^ / ~。

5. 版本管理 pyenv vs nvm

nvm 切换 Node 版本 → pyenv 切换 Python 版本。
Windows 上 pyenv 用 pyenv-win。
uv 也内置了 uv python install 3.12 / uv python pin 3.12 的版本管理能力，可替代 pyenv。

6. 运行 python main.py vs node index.js

node index.js        # → python main.py
node --version       # → python --version
node -e "console.log(1)"  # → python -c "print(1)"
node                  # 进入 REPL → python

7. 交互式 REPL

两者几乎一致，直接输入 python 进入交互式命令行，逐行执行代码。更强的增强版 REPL 可用 ipython（类似更强大的 console，支持自动补全、语法高亮）。

8. IDE 选择

VSCode：装微软官方 Python 扩展（含 Pylance，提供类型提示、跳转、重构），再配 Ruff 扩展做 lint。前端开发者零迁移成本。
PyCharm：JetBrains 出的 Python 专用 IDE，功能强大，适合大项目，但更重。

代码示例

安装 Python 与 uv（Windows，PowerShell）

# 1. 安装 uv（官方推荐方式，会自动处理 Python）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 用 uv 装一个指定版本的 Python（类似 nvm install 20）
uv python install 3.12

# 3. 确认版本
uv python --version

从零初始化一个项目

// 前端：初始化项目
// npm init -y && npm install axios

# Python：初始化项目
# uv init            → 生成 pyproject.toml
# uv add requests    → 安装依赖并更新 uv.lock
# uv run main.py     → 在虚拟环境里运行

对比：入口脚本

// index.js
console.log("Hello, World");

# main.py
print("Hello, World")

对比：模块入口守卫（防导入时执行）

// Node.js：CommonJS 下判断是否直接运行
if (require.main === module) {
  main();
}

# Python 惯用写法
if __name__ == "__main__":
    main()

最佳实践

新项目一律用 uv：uv init → uv add <pkg> → uv run python main.py，体验接近 npm init && npm i && npm start。
每个项目一个 .venv，绝不要把依赖装进全局环境（就像不要把全局依赖当项目依赖）。
提交代码时把 .venv/、__pycache__/ 写进 .gitignore（类比忽略 node_modules/）。
pyproject.toml 里写清楚 requires-python，锁定语言最低版本。
用 uv.lock 提交锁文件（类比提交 package-lock.json），保证团队环境一致。
装命令行工具用 uv tool install（类比 npm i -g），别污染项目环境。

前端开发者常见陷阱

忘了激活虚拟环境：直接 pip install 装到了全局，导致项目 A 装了包、项目 B 也能用，版本冲突。用 uv run/uv sync 可以根治。
python 命令指向的版本和预期不符：Windows 上可能同时装了 Python 2/3 或多个 3.x，python 和 py 可能指向不同版本。用 py -0 查看已装版本，或直接用 uv 管理。
以为有 npm run xxx 等价物：Python 没有官方脚本管理，pyproject.toml 里也没有 scripts。要么用 Makefile / just，要么用 uv run 跑一个入口脚本。
路径分隔符：Windows 下 venv 激活脚本在 .venv\Scripts\activate（反斜杠），macOS/Linux 是 .venv/bin/activate（正斜杠）。
把 python 当 node 直接用：node -e 对应 python -c，但 python 不能像 node 那样直接 python -p 之类，参数语义不同，别照搬。
忽略虚拟环境里解释器的路径：在 VSCode 里要手动选 .venv\Scripts\python.exe 作为解释器，否则 import 会找不到包。

总结

CPython 就是 Python 的"V8"，pip/uv 就是"npm"，PyPI 就是"npm registry"。
虚拟环境 venv 类比 node_modules，但隔离得更彻底（连解释器一起隔离）。
pyproject.toml ≈ package.json，uv.lock ≈ package-lock.json。
用 uv 启动新项目，体验最接近前端熟悉的 npm 工作流。
python main.py / python -c "..." / 裸 python 分别对应 node index.js / node -e / 裸 node。

Xxxxxy_112

0.1-环境搭建与运行