macOS Python版本管理指南概述本文档详细介绍如何在macOS系统上使用pyenv管理多个Python版本，包

概述

本文档详细介绍如何在macOS系统上使用pyenv管理多个Python版本，包括安装、切换和配置。

什么是pyenv？

pyenv是一个Python版本管理工具，允许您：

在同一系统上安装和管理多个Python版本
为不同项目设置不同的Python版本
轻松切换全局Python版本

安装pyenv

使用Homebrew安装（推荐）

# 安装pyenv
brew install pyenv

手动安装

# 克隆pyenv仓库
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

配置Shell环境

对于Zsh用户（macOS默认）

在 ~/.zshrc 文件中添加以下配置：

# 添加pyenv到PATH
export PATH="$HOME/.pyenv/bin:$PATH"

# 初始化pyenv
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

自动添加配置的命令：

echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

对于Bash用户

在 ~/.bash_profile 文件中添加：

echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile
echo 'eval "$(pyenv init -)"' >> ~/.bash_profile

重新加载Shell配置

# 重新加载配置文件
source ~/.zshrc
# 或者重启terminal
exec $SHELL

Python版本管理

查看可用版本

# 查看所有可安装的Python版本
pyenv install --list

# 查看已安装的版本
pyenv versions

安装特定Python版本

# 安装Python 3.9.6
pyenv install 3.9.6

# 安装其他版本示例
pyenv install 3.8.10
pyenv install 3.10.5
pyenv install 3.11.2

设置Python版本

全局设置（系统默认）

# 设置全局默认Python版本
pyenv global 3.9.6

# 查看当前全局版本
pyenv global

项目级设置

# 在项目目录中设置本地Python版本
cd /path/to/your/project
pyenv local 3.8.10

# 这会在当前目录创建 .python-version 文件

Shell会话设置

# 仅在当前shell会话中设置Python版本
pyenv shell 3.10.5

# 取消shell级别的设置
pyenv shell --unset

验证和调试

验证Python版本

# 检查Python版本
python --version
python3 --version

# 检查Python路径
which python
which python3

# 检查pyenv状态
pyenv version
pyenv versions

常见问题排查

1. python3命令仍指向系统Python

问题现象：

$ python3 --version
Python 3.13.0  # 仍然是系统版本

解决方案：

# 检查PATH
echo $PATH

# 检查shell配置
cat ~/.zshrc | grep pyenv

# 重新加载配置
source ~/.zshrc
exec $SHELL

2. PATH中缺少pyenv路径

检查命令：

echo $PATH | grep pyenv

如果没有输出，需要重新配置shell：

echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

3. 版本优先级问题

pyenv版本优先级（从高到低）：

pyenv shell - 当前shell会话
pyenv local - 当前项目目录
pyenv global - 全局默认
system - 系统Python

实际案例：从Python 3.13.0切换到3.9.6

步骤1：安装pyenv

brew install pyenv

步骤2：配置shell环境

echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

步骤3：安装Python 3.9.6

# 安装Python 3.9.6
pyenv install 3.9.6

# 如果版本已存在，选择重新安装或跳过
# pyenv: /Users/username/.pyenv/versions/3.9.6 already exists
# continue with installation? (y/N) y

步骤4：设置为全局默认版本

pyenv global 3.9.6

步骤5：验证切换结果

# 检查版本列表
pyenv versions
# 输出示例：
#   system
# * 3.9.6 (set by /Users/username/.pyenv/version)

# 验证Python版本
python3 --version
# 应该输出：Python 3.9.6

# 检查Python路径
which python3
# 应该输出：/Users/username/.pyenv/shims/python3

高级用法

管理多个项目

# 项目A使用Python 3.9.6
cd ~/projects/project-a
pyenv local 3.9.6

# 项目B使用Python 3.11.2
cd ~/projects/project-b
pyenv local 3.11.2

# 全局默认使用Python 3.10.5
pyenv global 3.10.5

卸载Python版本

# 卸载特定版本
pyenv uninstall 3.8.10

# 查看占用空间
du -sh ~/.pyenv/versions/*

更新pyenv

# 使用Homebrew更新
brew upgrade pyenv

# 手动安装的更新
cd ~/.pyenv
git pull

最佳实践

使用pyenv管理Python版本：避免直接从python.org安装多个版本
项目级版本控制：为每个项目设置特定的Python版本
定期清理：删除不再使用的Python版本以节省空间
备份配置：将shell配置文件加入版本控制
虚拟环境配合：结合venv或conda使用以获得更好的依赖管理

常用命令速查

# 查看命令
pyenv --help                 # 查看帮助
pyenv versions              # 列出已安装版本
pyenv install --list        # 列出可安装版本
pyenv version               # 查看当前使用版本

# 安装和卸载
pyenv install 3.9.6         # 安装指定版本
pyenv uninstall 3.9.6       # 卸载指定版本

# 版本切换
pyenv global 3.9.6          # 设置全局版本
pyenv local 3.9.6           # 设置项目版本
pyenv shell 3.9.6           # 设置会话版本

# 查看路径
which python                # Python可执行文件路径
echo $PATH                  # 环境变量PATH
pyenv which python          # pyenv管理的Python路径

故障排除

如果遇到问题，按以下顺序检查：

确认pyenv已正确安装：pyenv --version
检查shell配置：cat ~/.zshrc | grep pyenv
验证PATH设置：echo $PATH | grep pyenv
重新加载配置：source ~/.zshrc
检查Python版本：python3 --version

通过以上步骤，您就可以成功管理macOS上的多个Python版本了。

Django开发环境配置指南

概述

本部分介绍如何在macOS上配置Django开发环境，包括虚拟环境创建、Django安装和项目初始化。

前置条件

确保已经按照上述步骤配置好pyenv和Python环境：

# 确认Python版本
python3 --version
# 应该显示：Python 3.9.6（或您设置的版本）

# 确认pip可用
pip3 --version

虚拟环境管理

使用venv创建虚拟环境（推荐）

# 创建项目目录
mkdir ~/django-projects
cd ~/django-projects

# 创建Django项目目录
mkdir myproject
cd myproject

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate

# 确认虚拟环境已激活（命令提示符前会显示(venv)）
which python
# 应该显示：/Users/username/django-projects/myproject/venv/bin/python

使用virtualenv（可选）

# 安装virtualenv
pip3 install virtualenv

# 创建虚拟环境
virtualenv venv

# 激活虚拟环境
source venv/bin/activate

虚拟环境常用命令

# 激活虚拟环境
source venv/bin/activate

# 退出虚拟环境
deactivate

# 查看已安装的包
pip list

# 生成依赖文件
pip freeze > requirements.txt

# 从依赖文件安装
pip install -r requirements.txt

Django安装和配置

安装Django

# 确保虚拟环境已激活
source venv/bin/activate

# 安装最新版本的Django
pip install django

# 或安装指定版本
pip install django==4.2.7

# 确认Django安装成功
django-admin --version
python -m django --version

创建Django项目

# 在当前目录创建Django项目
django-admin startproject mysite .

# 或在新目录中创建项目
django-admin startproject mysite

# 项目结构如下：
# mysite/
#   manage.py
#   mysite/
#     __init__.py
#     settings.py
#     urls.py
#     asgi.py
#     wsgi.py

创建Django应用

# 进入项目目录
cd mysite

# 创建应用
python manage.py startapp myapp

# 应用结构如下：
# myapp/
#   __init__.py
#   admin.py
#   apps.py
#   migrations/
#     __init__.py
#   models.py
#   tests.py
#   views.py

数据库配置

默认SQLite配置

Django默认使用SQLite，无需额外配置：

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

配置PostgreSQL（推荐生产环境）

# 安装PostgreSQL
brew install postgresql

# 启动PostgreSQL服务
brew services start postgresql

# 创建数据库用户和数据库
createuser --interactive --pwprompt mysite_user
createdb --owner=mysite_user mysite_db

# 安装Python PostgreSQL适配器
pip install psycopg2-binary

在settings.py中配置：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mysite_db',
        'USER': 'mysite_user',
        'PASSWORD': 'your_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

配置MySQL

# 安装MySQL
brew install mysql

# 启动MySQL服务
brew services start mysql

# 安全设置（可选）
mysql_secure_installation

# 创建数据库和用户
mysql -u root -p
# 在MySQL命令行中执行：
# CREATE DATABASE mysite_db CHARACTER SET utf8mb4;
# CREATE USER 'mysite_user'@'localhost' IDENTIFIED BY 'your_password';
# GRANT ALL PRIVILEGES ON mysite_db.* TO 'mysite_user'@'localhost';
# FLUSH PRIVILEGES;
# EXIT;

# 安装Python MySQL适配器
pip install mysqlclient

在settings.py中配置：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'mysite_db',
        'USER': 'mysite_user',
        'PASSWORD': 'your_password',
        'HOST': 'localhost',
        'PORT': '3306',
        'OPTIONS': {
            'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
        },
    }
}

初始化项目

执行数据库迁移

# 创建迁移文件
python manage.py makemigrations

# 执行迁移
python manage.py migrate

# 查看迁移状态
python manage.py showmigrations

创建超级用户

# 创建管理员用户
python manage.py createsuperuser

# 按提示输入用户名、邮箱和密码

运行开发服务器

# 启动开发服务器
python manage.py runserver

# 指定端口
python manage.py runserver 8080

# 指定IP和端口
python manage.py runserver 0.0.0.0:8000

访问 http://127.0.0.1:8000 查看Django欢迎页面。

开发工具配置

安装常用Django包

# 激活虚拟环境
source venv/bin/activate

# 安装常用包
pip install django-debug-toolbar    # 调试工具栏
pip install django-extensions       # Django扩展
pip install pillow                  # 图像处理
pip install python-decouple        # 环境变量管理
pip install dj-database-url         # 数据库URL解析
pip install whitenoise              # 静态文件服务
pip install gunicorn               # WSGI服务器

# 保存依赖
pip freeze > requirements.txt

配置开发环境设置

创建 .env 文件管理环境变量：

# .env
DEBUG=True
SECRET_KEY=your-secret-key-here
DATABASE_URL=sqlite:///db.sqlite3

更新settings.py：

from decouple import config
import dj_database_url

# 基本配置
DEBUG = config('DEBUG', default=False, cast=bool)
SECRET_KEY = config('SECRET_KEY')

# 数据库配置
DATABASES = {
    'default': dj_database_url.config(
        default=config('DATABASE_URL')
    )
}

# 开发工具配置
if DEBUG:
    INSTALLED_APPS += ['debug_toolbar']
    MIDDLEWARE += ['debug_toolbar.middleware.DebugToolbarMiddleware']
    INTERNAL_IPS = ['127.0.0.1']

IDE配置

VS Code配置

安装推荐扩展：

Python
Django
Python Docstring Generator
GitLens

创建 .vscode/settings.json：

{
    "python.defaultInterpreterPath": "./venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "black",
    "python.linting.flake8Enabled": true,
    "emmet.includeLanguages": {
        "django-html": "html"
    },
    "files.associations": {
        "**/*.html": "django-html"
    }
}

PyCharm配置

打开PyCharm
选择项目目录
配置Python解释器：Settings > Project > Python Interpreter
选择虚拟环境中的Python：./venv/bin/python
启用Django支持：Settings > Languages & Frameworks > Django

项目结构最佳实践

分环境配置

base.py (基础配置):

import os
from pathlib import Path
from decouple import config

BASE_DIR = Path(__file__).resolve().parent.parent.parent

SECRET_KEY = config('SECRET_KEY')

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # 本地应用
    'apps.blog',
    'apps.users',
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

ROOT_URLCONF = 'mysite.urls'

development.py (开发环境):

from .base import *

DEBUG = True
ALLOWED_HOSTS = ['localhost', '127.0.0.1']

# 开发数据库
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

# 调试工具
INSTALLED_APPS += ['debug_toolbar']
MIDDLEWARE += ['debug_toolbar.middleware.DebugToolbarMiddleware']
INTERNAL_IPS = ['127.0.0.1']

production.py (生产环境):

from .base import *
import dj_database_url

DEBUG = False
ALLOWED_HOSTS = config('ALLOWED_HOSTS', cast=lambda v: [s.strip() for s in v.split(',')])

# 生产数据库配置
DATABASES = {
    'default': dj_database_url.config(
        default=config('DATABASE_URL')
    )
}

# 安全设置
SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_PRELOAD = True
SECURE_HSTS_INCLUDE_SUBDOMAINS = True

常用Django命令

项目管理命令

# 创建项目和应用
django-admin startproject mysite
python manage.py startapp myapp

# 数据库操作
python manage.py makemigrations
python manage.py migrate
python manage.py sqlmigrate app_name migration_name
python manage.py showmigrations

# 用户管理
python manage.py createsuperuser
python manage.py changepassword username

# 服务器运行
python manage.py runserver
python manage.py runserver 8080
python manage.py runserver 0.0.0.0:8000

# 静态文件
python manage.py collectstatic
python manage.py findstatic filename

# Shell和测试
python manage.py shell
python manage.py test
python manage.py test app_name.tests.TestClass.test_method

实用命令

# 检查项目配置
python manage.py check
python manage.py check --deploy

# 清理会话
python manage.py clearsessions

# 显示URL配置
python manage.py show_urls  # 需要django-extensions

# 导入导出数据
python manage.py dumpdata > data.json
python manage.py loaddata data.json

# 创建迁移文件（不执行）
python manage.py makemigrations --dry-run
python manage.py makemigrations --empty app_name

部署准备

生产环境清单

# 安装生产依赖
pip install gunicorn
pip install whitenoise
pip install psycopg2-binary

# 配置静态文件
python manage.py collectstatic

# 检查部署配置
python manage.py check --deploy

# 运行测试
python manage.py test

Docker配置（可选）

创建 Dockerfile：

FROM python:3.9.6-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["gunicorn", "--bind", "0.0.0.0:8000", "mysite.wsgi:application"]

创建 docker-compose.yml：

version: '3.8'

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DEBUG=False
    depends_on:
      - db
  
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: mysite_db
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data/

volumes:
  postgres_data:

故障排除

常见问题

虚拟环境未激活

确认虚拟环境激活

which python

应该显示虚拟环境路径
Django导入错误

确认Django安装

pip show django python -c "import django; print(django.get_version())"
数据库连接错误

检查数据库配置

python manage.py dbshell

重新创建数据库

python manage.py flush python manage.py migrate
静态文件问题

收集静态文件

python manage.py collectstatic --clear

检查静态文件配置

python manage.py findstatic admin/css/base.css

通过以上配置，您就可以在macOS上成功搭建Django开发环境了。建议从简单的SQLite配置开始，随着项目发展再考虑切换到PostgreSQL等生产级数据库。

macOS Python版本管理指南

概述

什么是pyenv？

安装pyenv

使用Homebrew安装（推荐）

手动安装

配置Shell环境

对于Zsh用户（macOS默认）

对于Bash用户

重新加载Shell配置

Python版本管理

查看可用版本

安装特定Python版本

设置Python版本

全局设置（系统默认）

项目级设置

Shell会话设置

验证和调试

验证Python版本

常见问题排查

1. python3命令仍指向系统Python

2. PATH中缺少pyenv路径

3. 版本优先级问题

实际案例：从Python 3.13.0切换到3.9.6

步骤1：安装pyenv

步骤2：配置shell环境

步骤3：安装Python 3.9.6

步骤4：设置为全局默认版本

步骤5：验证切换结果

高级用法

管理多个项目

卸载Python版本

更新pyenv

最佳实践

常用命令速查

故障排除

Django开发环境配置指南

概述

前置条件

虚拟环境管理

使用venv创建虚拟环境（推荐）

使用virtualenv（可选）

虚拟环境常用命令

Django安装和配置

安装Django

创建Django项目

创建Django应用

数据库配置

默认SQLite配置

配置PostgreSQL（推荐生产环境）

配置MySQL

初始化项目

执行数据库迁移

创建超级用户

运行开发服务器

开发工具配置

安装常用Django包

配置开发环境设置

IDE配置

VS Code配置

PyCharm配置

项目结构最佳实践

推荐的项目结构

分环境配置

常用Django命令

项目管理命令

实用命令

部署准备

生产环境清单

Docker配置（可选）

故障排除

常见问题

确认虚拟环境激活

应该显示虚拟环境路径

确认Django安装

检查数据库配置

重新创建数据库

收集静态文件

检查静态文件配置