VS Code 终端运行 Python 文件的基础操作与命令

一、打开集成终端与确认当前路径

VS Code 的集成终端是一个直接嵌入在编辑器底部的系统 Shell（如 Windows 的 PowerShell/CMD，macOS 与 Linux 的 zsh/bash）。在终端运行 Python 之前，首先必须调出终端窗口并确认当前所处的路径。

1. 调出终端面板的快捷方式

在编辑 Python 文件的过程中，可以通过以下两种方式随时打开终端：

• 键盘快捷键：在 Windows/Linux 下按下 Ctrl + `（波浪键/反引号键），在 macOS 下按下 Control + `。如果终端已被隐藏，该快捷键会展开它；如果再次按下则会收起面板。
• 顶部菜单：点击顶部菜单栏的「终端（Terminal）」>「新建终端（New Terminal）」。编辑器将在底部创建并载入一个干净的命令行会话。

2. 核心概念：当前工作目录（CWD）

许多初学者直接在终端敲击 python main.py 却频繁遭遇错误，主要原因在于忽略了当前工作目录（Current Working Directory，简称 CWD）。VS Code 默认打开终端时，其工作目录通常是你在 VS Code 中打开的工作区根文件夹，而不是你正在编辑的代码文件所在的子文件夹。

可以通过以下命令查看终端当前停留在哪个路径：

# macOS / Linux 系统查看当前路径：
pwd

# Windows PowerShell 查看当前路径：
Get-Location
# 或直接输入简写：
cd

如果你的代码文件 calculator.py 正好存放在 data-analysis 根目录下，那么直接在终端调用即可；如果代码文件存放在 src/utils/calculator.py，则必须切换路径或带上子目录路径。

图 1：从打开终端、核对路径到命令下发与结果捕获的标准四步流程

二、基础运行命令：python 与 python3 的执行方式

当终端所处目录明确后，运行 Python 文件的命令结构非常统一，基本形式由解释器可执行文件名加上目标脚本文件路径组成。

1. 不同操作系统下的调用名称

不同操作系统在安装 Python 时注册的可执行程序名称可能存在差异：

2. 完整执行示例与回显分析

假设我们有一个简单的 Python 文件 app.py，内容如下：

import sys

print("Python 脚本开始运行...")
print(f"当前使用的解释器路径: {sys.executable}")
print("计算任务完成，准备退出。")

在 VS Code 终端中输入执行命令：

~/projects/data-analysis$ python3 app.py

可以看到，命令执行后，终端依次打印出了程序的标准输出（stdout），执行完毕后自动返回命令行等待提示符 ~/projects/data-analysis$ ，表明程序已经正常退出。

图 2：终端调用 Python 命令的四大组成要素与参数映射机制

三、相对路径与绝对路径：避免“找不到文件”的核心规则

在终端中运行 Python，最常见的问题是终端提示找不到指定的 .py 文件。理解路径解析规则是规避该问题的关键。

1. 相对路径的三种常见用法

相对路径是相对于终端当前工作目录而言的，主要有以下三种情景：

• 同级文件执行：文件就在当前目录下，直接输入文件名：

  python app.py

• 子目录文件执行：文件存放在子文件夹中，无需先 cd 进入子目录，可直接书写相对路径：

  python src/models/train.py

  这种做法的好处是，脚本在读取项目根目录的配置文件或数据集时，依然以项目根目录为基准，不会因为切换目录导致路径错乱。

• 先切换目录再执行：使用 cd 命令切入目标文件夹后再运行：

  cd src/models
  python train.py

2. 绝对路径与文件拖拽技巧

如果你不确定当前路径与目标文件的相对层级，可以直接使用绝对路径调用。在 VS Code 中有一个非常实用的操作技巧：在终端中先输入 python （带空格），然后从左侧资源管理器中用鼠标把 .py 文件直接拖进终端窗口，VS Code 会自动为你填入该文件的完整绝对路径并转义特殊字符。

user@host:~$ python3 "/Users/username/projects/data-analysis/src/app.py"

图 3：终端直接执行与编辑器右上角“运行按钮”在运行机制与环境绑定上的核心差异

四、虚拟环境（venv / conda）在终端中的识别与激活

在实际项目开发中，通常会为项目创建独立的虚拟环境（如 venv 或 conda），以便隔离第三方依赖包。初学者常遇到的一个典型困惑是：“明明已经在 VS Code 里通过 pip 安装了模块，为什么在终端一运行依然报错 ModuleNotFoundError？”

1. 检查终端是否进入了虚拟环境

当终端成功激活虚拟环境时，终端每一行的最左侧通常会出现带有括号的环境名称标志，例如：

• (.venv) user@host:~/project$ （基于 Python 标准库 venv 创建的环境）
• (my_project_env) user@host:~/project$ （基于 Anaconda / Miniconda 创建的环境）

如果你的终端左侧没有任何括号前缀，说明当前终端会话使用的是操作系统的全局默认 Python，此时运行脚本将无法读取虚拟环境内安装的第三方包。

2. 手动激活虚拟环境的命令

通常 VS Code 会在打开终端时自动尝试激活检测到的虚拟环境，但如果自动激活未触发，可以在终端中手动执行激活脚本：

# Windows PowerShell 环境：
.\.venv\Scripts\Activate.ps1

# Windows CMD 环境：
.venv\Scriptsctivate.bat

# macOS / Linux 环境：
source .venv/bin/activate

3. 验证当前生效的解释器路径

激活后，随时可以使用以下命令核查终端当前调用的具体是哪一个 Python 可执行文件：

# macOS / Linux:
which python3

# Windows PowerShell:
Get-Command python | Select-Object -ExpandProperty Source
# Windows CMD:
where python

只要输出路径包含项目文件夹下的 .venv，就说明终端已经准确绑定了项目的私有虚拟环境。

五、常见终端运行报错与排错自检清单

在终端运行 Python 脚本遇到阻碍时，绝大多数情况属于环境配置或路径输入问题。下表列出三大高频报错及其快速修复方案：

图 4：VS Code 终端运行 Python 常见错误根因排查与对应操作清单

1. 错误：command not found 或 “不是内部或外部命令”

原因分析：操作系统无法在环境变量 PATH 登记的文件夹中找到名为 python 的可执行程序。

解决步骤：

1. 如果是在 macOS 或 Linux 上，改用 python3 main.py 尝试。
2. 如果是在 Windows 上，改用 py main.py 尝试。
3. 若均无响应，说明安装 Python 时未勾选“Add python.exe to PATH”。可以重新运行 Python 安装包，选择“Modify”，勾选环境变量选项，并在修改后彻底重启 VS Code。

2. 错误：can't open file 'xxx.py': [Errno 2] No such file or directory

原因分析：终端在当前工作目录下找不到该文件名，通常是因为拼写错误、文件存放在子目录，或者终端停留在别的文件夹。

解决步骤：

1. 运行 pwd（Windows 下使用 Get-Location）确认当前所在位置。
2. 运行 ls（Windows 下运行 dir）列出当前目录的所有文件，核对目标文件名的大小写与拼写。
3. 如果不一致，使用 cd 目标目录 切换，或者书写完整的相对路径。

3. 错误：ModuleNotFoundError: No module named 'xxx'

原因分析：代码中引用的第三方库尚未安装，或者安装在虚拟环境中，但当前终端并没有激活该虚拟环境。

解决步骤：

1. 查看终端提示符左侧是否有 (.venv) 前缀。
2. 若无前缀，先执行激活命令：source .venv/bin/activate（macOS/Linux）或 .\.venv\Scripts\Activate.ps1（Windows）。
3. 激活后，使用 pip list 确认所需模块是否在此环境中安装；若未安装，运行 pip install xxx 重新安装。