init

.gitignore

@@ -0,0 +1,23 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.env
+.env.*
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

note/base.md

@@ -0,0 +1,198 @@
+# Python 虚拟环境说明
+
+本文档介绍如何在 Python 项目中创建、激活、管理和清理虚拟环境，以确保每个项目都拥有独立、可复现的依赖环境。
+
+## 目录
+
+- [为什么需要虚拟环境](#为什么需要虚拟环境)
+- [创建虚拟环境](#创建虚拟环境)
+- [激活虚拟环境](#激活虚拟环境)
+- [检查环境状态](#检查环境状态)
+- [安装依赖包](#安装依赖包)
+- [退出虚拟环境](#退出虚拟环境)
+- [删除虚拟环境](#删除虚拟环境)
+- [常见问题](#常见问题)
+- [最佳实践](#最佳实践)
+- [命令速查](#命令速查)
+
+## 为什么需要虚拟环境
+
+虚拟环境可以让每个 Python 项目拥有独立的解释器和第三方库环境，带来以下好处：
+
+- 避免不同项目之间的依赖冲突
+- 防止全局 Python 环境被污染
+- 便于在开发、测试和部署中保持一致
+- 方便在不同 Python 版本之间切换
+
+## 创建虚拟环境
+
+在项目根目录中执行以下命令：
+
+### Windows
+```bash
+python -m venv .venv
+```
+
+### macOS / Linux
+```bash
+python3 -m venv .venv
+```
+
+如果系统中安装了多个 Python 版本，可以指定版本：
+
+### Windows
+```bash
+py -3.11 -m venv .venv
+```
+
+### macOS / Linux
+```bash
+python3.11 -m venv .venv
+```
+
+执行完成后，当前目录会生成一个 `.venv` 目录，用于保存该虚拟环境的文件。
+
+## 激活虚拟环境
+
+### Windows (Command Prompt)
+```bash
+.venv\Scripts\activate
+```
+
+### Windows (PowerShell)
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+### macOS / Linux
+```bash
+source .venv/bin/activate
+```
+
+成功激活后，命令提示符通常会显示环境名称，例如：
+
+```bash
+(.venv) C:\project\>
+```
+
+## 检查环境状态
+
+在虚拟环境中，可以验证当前 Python 和 pip 是否来自当前环境：
+
+```bash
+python --version
+pip --version
+```
+
+也可以查看当前解释器位置：
+
+```bash
+which python
+```
+
+在 Windows PowerShell 中：
+
+```powershell
+Get-Command python
+```
+
+## 安装依赖包
+
+在激活虚拟环境之后，安装项目依赖：
+
+```bash
+pip install requests
+```
+
+如果项目中已有依赖清单：
+
+```bash
+pip install -r requirements.txt
+```
+
+如果需要导出当前环境中的依赖：
+
+```bash
+pip freeze > requirements.txt
+```
+
+## 退出虚拟环境
+
+开发完成后，可以退出虚拟环境：
+
+```bash
+deactivate
+```
+
+## 删除虚拟环境
+
+如果不再需要该环境，可以直接删除虚拟环境目录：
+
+### Windows
+```bash
+rmdir /s /q .venv
+```
+
+### macOS / Linux
+```bash
+rm -rf .venv
+```
+
+## 常见问题
+
+### 1. `python` 命令找不到
+
+通常是因为没有将 Python 添加到系统 PATH。可以检查安装后的 Python 路径，或使用 `py`（Windows）或 `python3`（macOS / Linux）。
+
+### 2. PowerShell 无法激活脚本
+
+如果遇到脚本执行策略限制，可以在 PowerShell 中执行：
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+```
+
+然后再次尝试激活虚拟环境。
+
+### 3. 依赖包安装失败
+
+可以先升级 pip：
+
+```bash
+python -m pip install --upgrade pip
+```
+
+然后重新安装依赖。
+
+## 最佳实践
+
+- 每个项目使用独立的虚拟环境
+- 将依赖写入 `requirements.txt`，便于复现和部署
+- 不要将 `.venv` 目录提交到版本控制系统中
+- 在团队协作中，建议通过 `requirements.txt` 或 `pyproject.toml` 统一环境配置
+
+## 命令速查
+
+```bash
+# 创建虚拟环境
+python -m venv .venv
+
+# Windows 激活
+.venv\Scripts\activate
+
+# PowerShell 激活
+.\.venv\Scripts\Activate.ps1
+
+# macOS / Linux 激活
+source .venv/bin/activate
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 退出虚拟环境
+deactivate
+```
+
+## 结论
+
+Python 虚拟环境是 Python 项目开发中的基础实践之一。通过合理使用虚拟环境，可以更稳定地管理依赖、减少环境冲突，并提升项目的可维护性和可复现性。