环境、解释器与项目基线

本篇建立整个系列共用的开发环境。目标不是罗列安装界面，而是弄清楚“当前执行的是哪个 Python、依赖安装到了哪里、模块为何能够被找到”。

一、学习目标

区分解释器、标准库、pip、虚拟环境和项目
在 Windows、Linux、macOS 上确认实际解释器
创建 study_tasks 项目与 src 目录
理解脚本运行和模块运行的差异
建立可重复的最小工作流

前置条件：能使用终端并理解绝对路径与相对路径。

二、确认 Python 3.14

Linux 或 macOS：

python3.14 --version
python3.14 -c "import sys; print(sys.executable)"

Windows PowerShell：

py --list
py -3.14 --version
py -3.14 -c "import sys; print(sys.executable)"

sys.executable 比命令名称更可靠，它显示当前进程真正使用的解释器路径。进入虚拟环境后再次执行，路径应指向 .venv。

三、创建虚拟环境

mkdir study_tasks
cd study_tasks
python3.14 -m venv .venv

Linux/macOS：

source .venv/bin/activate

Windows PowerShell：

py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1

验证隔离结果：

python --version
python -c "import sys; print(sys.prefix)"
python -m pip --version

推荐使用 python -m pip，因为它明确要求“由当前这个 Python 运行 pip”，可以避免 pip 命令指向另一个环境。

四、建立项目结构

study_tasks/
  pyproject.toml
  README.md
  src/
    study_tasks/
      __init__.py
      __main__.py
  tests/

最小 pyproject.toml：

[build-system]
requires = ["hatchling>=1.27"]
build-backend = "hatchling.build"

[project]
name = "study-tasks"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = []

[tool.hatch.build.targets.wheel]
packages = ["src/study_tasks"]

src 布局可以避免测试时意外导入项目根目录中的同名文件，迫使开发环境更接近真正安装后的状态。

五、脚本与模块

创建 src/study_tasks/__main__.py：

def main() -> None:
    print("study_tasks 已就绪")


if __name__ == "__main__":
    main()

安装并运行：

python -m pip install -e .
python -m study_tasks

python file.py 把文件当作脚本执行；python -m package 通过导入系统定位模块。包内部存在相对导入时，优先使用模块方式或安装后的命令行入口。

六、解释器如何寻找模块

检查搜索路径：

python -c "import sys; print(*sys.path, sep='\n')"

导入一个模块时，Python 会在 sys.path 中依次寻找。不要通过在代码里随意修改 sys.path 修复项目结构；正确做法是把项目声明为包并安装到虚拟环境。

检查实际导入位置：

python -c "import study_tasks; print(study_tasks.__file__)"

路径应该指向当前项目的 src/study_tasks。

七、REPL 与一次性诊断

进入交互式解释器：

python

适合快速验证对象和 API：

>>> from pathlib import Path
>>> Path.cwd()
>>> [name.upper() for name in ["read", "test"]]
['READ', 'TEST']

一次性诊断可使用 -c：

python -c "import platform; print(platform.python_version())"

不要把多步骤业务逻辑长期保存在 shell 历史里；一旦需要复用或测试，就移动到模块和函数中。

八、常见错误

安装后仍然无法导入

先执行：

python -m pip show study-tasks
python -c "import sys; print(sys.executable)"

最常见原因是安装依赖和运行程序用了不同解释器。

PowerShell 禁止激活脚本

可只对当前进程放宽：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

也可以不激活，直接运行：

.\.venv\Scripts\python.exe -m pip install -e .

项目里出现 `random.py` 或 `typing.py`

这些文件会遮蔽同名标准库模块。为自己的模块选择更具体的名字。

九、练习与自测

不激活虚拟环境，直接用 .venv 内的解释器运行模块。
打印 sys.executable、sys.prefix 和 study_tasks.__file__。
新建同名顶层文件观察导入冲突，然后删除它。

自测：

能否解释 python -m pip 比单独 pip 更明确的原因？
python -m study_tasks 如何找到 __main__.py？
为什么项目采用 src 布局？

十、官方资料

上一篇：Python 完整学习路线｜下一篇：语法、对象与数据类型