Ir al contenido

Настройка Python и .venv в VS Code

Решение проблем интерпретации и виртуальных сред с помощью VS Code под Windows.

0просмотры

Это руководство предоставляет окончательную техническую процедуру для диагностики, настройки и реализации сред разработки Python в Visual Studio Code под системами Windows. Оно охватывает все, от правильного назначения глобальных интерпретаторов (включая нестандартные пути winget или Microsoft Store) до автоматизации и установки зависимостей в изолированных средах (.venv).


1. Основы архитектуры

Sección titulada «1. Fundamentos de Arquitectura»

Чтобы обеспечить предсказуемую среду разработки, важно разделить интерфейс пользователя от двигателя выполнения и пакетов зависимостей каждого проекта.

Интерпретатор vs. Редактор

Sección titulada «El Intérprete vs. El Editor»
  • Visual Studio Code (UI/Редактор): Работает строго как расширенный текстовый редактор и интегрированная среда разработки. Не включает в себя встроенный движок Python; вместо этого делегирует выполнение кода внешнему интерпретатору.
  • Движок Python (python.exe): Это бинарный файл, ответственный за обработку и интерпретацию инструкций кода. Выполняется напрямую на системе или внутри под сред.

Глобальная среда vs. Виртуальная среда (.venv)

Sección titulada «Entorno Global vs. Entorno Virtual (.venv)»
  • Python Глобальный: Соответствует базовой установке системы. Acts как начальная шаблон и не должен изменяться с помощью внешних пакетов, чтобы избежать конфликтов зависимостей между различными проектами.
  • Виртуальные среды (.venv): Это изолированные под каталоги, которые инкапсулируют свой собственный бинарный файл Python и дерево зависимостей (site-packages).
┌──────────────────────────────────────────────────────────┐
│                   Sistema Operativo                      │
│   (Python Global - Instalación base libre de paquetes)   │
└────────────────────────────┬─────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
   ┌────────────────────┐        ┌────────────────────┐
   │    Proyecto A      │        │    Proyecto B      │
   │  (.venv A - Aislado)│        │  (.venv B - Aislado)│
   │  - Pandas v1.0     │        │  - Pandas v2.0     │
   │  - Requests        │        │  - Gemini API      │
   └────────────────────┘        └────────────────────┘

2. Процедура настройки шаг за шагом

Sección titulada «2. Procedimiento de Configuración Paso a Paso»

Строго следуйте следующему порядку, чтобы обеспечить инициализацию и выполнение Python в рабочей области без ошибок зависимостей.

Шаг 1: Установка официального расширения

Sección titulada «Paso 1: Instalación de la Extensión Oficial»
  1. Перейдите на вкладку Расширения в VS Code (Ctrl + Shift + X).
  2. Найдите официальное расширение Python, разработанное компанией Microsoft.
  3. Нажмите Установить. Это расширение включает возможности отладки, IntelliSense и динамического управления интерпретаторами в редакторе.

Шаг 2: Находка глобального интерпретатора (Случаи winget)

Sección titulada «Paso 2: Localización del Intérprete Global (Casos de winget)»

Когда Python устанавливается через менеджеры пакетов, такие как winget или Microsoft Store, часто бывает так, что установщик не регистрирует исполняемый файл в стандартных системных путях (PATH). Чтобы найти базовый исполняемый файл:

  1. Откройте терминал команд в вашей системе (CMD или PowerShell).
  2. Выполните следующую команду поиска:
Ventana de terminal
where.exe python
  1. Терминал вернет абсолютный путь к активному исполняемому файлу. Например: C:\Program Files\Python312\python.exe или C:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. Сохраните этот путь.

Шаг 3: Инициализация виртуальной среды (.venv)

Sección titulada «Paso 3: Inicialización del Entorno Virtual (.venv)»

Чтобы избежать сбоев или блокирующих диалоговых окон в интегрированных меню VS Code, создайте среду непосредственно из терминала редактора:

  1. Откройте интегрированную терминал в VS Code (Ctrl + Ñ или Ctrl + ~).
  2. Выполните стандартный модуль виртуальной среды, указав имя директории .venv:
Ventana de terminal
python -m venv .venv
  1. После завершения выполнения будет создан новый каталог .venv в корне вашего рабочего пространства.

Шаг 4: Связывание интерпретатора VS Code с виртуальной средой

Sección titulada «Paso 4: Vinculación del Intérprete de VS Code con el Entorno Virtual»

Создание подкаталога .venv не активирует соединение в редакторе. Вам необходимо принудительно заставить VS Code использовать только что созданный интерпретатор:

  1. Убедитесь, что у вас открыт и выбран хотя бы один файл с расширением .py в редакторе VS Code (это активирует контекстный двигатель Python).
  2. Откройте Палитру Команд, используя Ctrl + Shift + P.
  3. Введите и выберите Python: Select Interpreter (Python: Выберите Интерпретатор).
  4. Редактор представит список. Выберите опцию, которая указывает напрямую на вашу локальную среду. Обычно она указывается как рекомендуемая:
Ventana de terminal
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe
  1. Проверка состояния: Посмотрите в правый нижний угол панели состояния VS Code.
    • ✕ Неверный Путь: Отображает Python 3.x.x (вы используете бинарный файл глобальной системы).
    • ✓ Верный Путь: Отображает Python 3.x.x ('.venv') (среда правильно связана).

Шаг 5: Активация консоли и установка зависимостей

Sección titulada «Paso 5: Activación de la Consola e Instalación de Dependencias»

Как только интерпретатор связан в редакторе, каждый новый открытый терминал будет автоматически наследовать активную виртуальную среду.

  1. Откройте новую интегрированную терминал (Ctrl + Ñ).
  2. Проверьте, что подсказка команды отображает префикс активации в крайнем левом углу:
Ventana de terminal
(.venv) PS C:\MiProyecto>
  1. Установите необходимые библиотеки проекта непосредственно внутри вашей изолированной среды:
Ventana de terminal
pip install google-generativeai requests pandas

3. Решение проблем (Устранение неполадок)

Sección titulada «3. Resolución de Problemas (Troubleshooting)»
СимптомКоренная причинаРешение
Интегрированное меню Create Environment запрашивает ручной ввод пути и зависает.VS Code не может автоматически обнаружить базовую установку Python в PATH системы (обычно при установке через winget).Отмените интегрированный диалог. Следуйте шагу 3 этого руководства, чтобы создать среду вручную через терминал с помощью python -m venv .venv.
Ошибка ModuleNotFoundError: No module named '<libreria>' при нажатии «Play». Код выполняется интерпретатором, отличным от того, который содержит установленные пакеты (обычно глобальный).1. Проверьте правую нижнюю часть VS Code, чтобы подтвердить, что у вас связан субинтерпретатор ('.venv').
2. Если нет, повторите шаг 4 (Select Interpreter).
Терминал не отображает префикс (.venv) при открытии.Текущая консоль не была обновлена после настройки интерпретатора или имеет ограниченные политики выполнения в PowerShell.1. Закройте все активные терминалы с помощью иконки мусорного бака в нижней панели.
2. Откройте совершенно новую терминал (Ctrl + Ñ). Скрипт активации будет выполнен автоматически.
Селектор версии Python не отображается в строке состояния VS Code.Редактор не загрузил контекстные службы Python, потому что нет открытых файлов кода.Откройте любой файл с расширением .py в вашем основном редакторе, чтобы принудительно инициализировать расширение Microsoft.