1. 为什么在Mac上安装Django值得你花时间如果你是一个在Mac上搞开发的Pythoner想快速搭建一个Web应用或者正从Flask、FastAPI等其他框架转过来那么Django几乎是你绕不开的一个选择。它不像某些轻量级框架那样“缺胳膊少腿”Django自诩为“完美主义者的最后期限框架”意思就是它自带了你开发一个成熟Web应用所需的大部分轮子——从用户认证、后台管理到ORM和表单处理开箱即用。这能让你把精力集中在业务逻辑上而不是反复造轮子。但问题来了很多新手甚至一些有经验的开发者在Mac这个看似优雅的系统上安装Django时总会遇到一些“水土不服”的问题。比如系统自带的Python 2.7虽然现在新系统已经移除了但影响深远、多个Python版本共存导致的路径混乱、或者用了pip安装后却找不到django-admin命令。这些坑我当年一个没落全踩了一遍。所以这篇教程的目的不仅仅是告诉你敲哪几条命令更重要的是帮你理清Mac下Python环境管理的逻辑让你一次配置长久受益避免未来在依赖地狱里挣扎。我们将从最干净、最推荐的方式开始使用pyenv管理Python版本再用pip安装Django。同时我也会对比直接使用系统Python、Homebrew安装Python等不同方案的利弊让你知其然更知其所以然。无论你是刚拿到新Mac的萌新还是想重整开发环境的老手这篇超过5000字的详实指南都能带你平滑上路。2. 环境基石为Django选择合适的Python家园在安装Django之前最重要的一步是准备好一个独立、干净的Python环境。Mac系统环境比较复杂直接使用系统Python是极其不推荐的做法原因有三第一系统Python的路径受系统保护随意安装包可能需要sudo容易引发权限问题并污染系统环境第二macOS系统组件可能依赖特定版本的Python你的操作可能导致系统功能异常第三无法实现项目间Python版本的隔离。因此我们的核心思路是为开发项目创建一个独立的、可复制的Python环境。主流方案有两个虚拟环境Virtual Environment配合Python版本管理工具或者使用Anaconda这类科学计算发行版。对于Web开发特别是Django我强烈推荐前者因为它更轻量、更符合Python生态的标准实践。2.1 方案对比pyenv venv 还是 Homebrew Python这是Mac用户最常面临的选择题。我们来拆解一下直接使用Homebrew安装的Python Homebrew安装的Python例如brew install python3.11本身是一个独立的、较新版本的Python比系统Python好。但它仍然是一个“全局”安装。如果你需要为不同项目切换不同的Python版本比如一个项目用3.8另一个用3.11你需要反复brew unlink和brew link非常麻烦且容易出错。因此它适合作为系统默认Python的升级替代但不适合多版本项目管理。使用pyenv管理多版本再结合venv创建虚拟环境 这是目前社区公认的最佳实践。pyenv是一个纯粹的Python版本管理工具它可以让你在同一台机器上安装多个版本的Python并轻松地在它们之间切换。而venvPython 3.3内置或virtualenv第三方则用于在某个Python版本下为每个项目创建独立的包安装目录解决项目依赖冲突。优势版本切换灵活环境隔离彻底与项目目录绑定可复制性强通过requirements.txt。我们的选择本教程将以此方案为主线进行详解。2.2 第一步安装Homebrew如果尚未安装Homebrew是Mac的包管理器几乎是Mac开发者的标配。我们将用它来安装pyenv。 打开终端Terminal执行以下命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)安装过程中可能会提示你安装Xcode Command Line Tools按提示确认即可。安装完成后根据终端最后的提示将Homebrew的可执行文件路径添加到你的shell配置文件如~/.zshrc 如果你用的是Zsh这是macOS Catalina及之后版本的默认shell中。命令通常如下echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zshrc source ~/.zshrc注意如果你使用的是较旧的Mac或Bash shell配置文件可能是~/.bash_profile。使用echo $SHELL可以查看当前shell。2.3 第二步使用Homebrew安装并配置pyenv通过Homebrew安装pyenv非常简单brew update brew install pyenv安装完成后我们需要配置shell让pyenv能够自动工作。将以下内容添加到你的~/.zshrc或~/.bash_profile文件末尾export PYENV_ROOT$HOME/.pyenv [[ -d $PYENV_ROOT/bin ]] export PATH$PYENV_ROOT/bin:$PATH eval $(pyenv init -)然后让配置生效source ~/.zshrc现在你可以验证pyenv是否安装成功pyenv --version2.4 第三步用pyenv安装所需的Python 3版本首先查看pyenv可以安装哪些Python版本pyenv install --list | grep 3\.你会看到一个很长的列表。建议选择当前稳定的、且Django官方支持良好的版本。例如Django 4.2 LTS支持Python 3.8到3.11。我们选择安装Python 3.11.9请以最新稳定版为准pyenv install 3.11.9这个过程会从源码编译Python需要一些时间请耐心等待。如果遇到编译错误通常是缺少某些依赖库。常见的解决方法是使用Homebrew安装这些依赖brew install openssl readline sqlite3 xz zlib tcl-tk安装完成后我们可以查看当前系统所有通过pyenv管理的Python版本pyenv versions输出中带星号(*)的是当前全局激活的版本通常是系统版本。现在我们将刚安装的Python 3.11.9设置为全局默认版本pyenv global 3.11.9再次执行pyenv versions你应该能看到3.11.9前面有了星号。验证一下python --version # 应输出Python 3.11.9 which python # 应输出/Users/你的用户名/.pyenv/shims/python这个路径说明Python命令已经被pyenv接管指向了我们指定的版本。3. 创建项目专属的虚拟环境现在我们有了干净的Python 3.11.9接下来要为Django项目创建独立的虚拟环境。虚拟环境的核心价值在于“隔离”。想象一下你项目A需要Django 4.2项目B需要Django 3.2如果没有虚拟环境这两个版本在全局安装会冲突。虚拟环境为每个项目提供了一个独立的Python运行环境和pip包安装目录。3.1 创建项目目录并初始化虚拟环境首先为你未来的Django项目创建一个总目录并进入mkdir ~/Projects cd ~/Projects然后创建你的第一个Django项目目录比如叫myblogmkdir myblog cd myblog现在在这个项目目录下使用Python内置的venv模块创建虚拟环境。虚拟环境目录通常命名为venv或.venvpython -m venv venv这条命令会在myblog文件夹内创建一个名为venv的子目录里面包含了一个独立的Python解释器、pip工具等。3.2 激活与使用虚拟环境创建后你需要“激活”这个环境这样后续的所有python和pip命令才会作用于这个隔离的环境。激活source venv/bin/activate激活后你的命令行提示符前通常会显示环境名如(venv) ~/Projects/myblog $。验证which python # 应输出/Users/你的用户名/Projects/myblog/venv/bin/python pip --version # 会显示pip的版本和其所在的路径应在venv目录内停用 当你完成工作想退出当前虚拟环境时只需执行deactivate提示符前的(venv)会消失。重要心得养成习惯进入项目目录后第一件事就是激活虚拟环境。很多“ModuleNotFoundError”错误都是因为在没有激活环境的情况下安装包或运行程序导致的。你可以将激活命令写在项目目录的.env文件或shell别名里来简化操作。4. 安装Django及其最佳搭档虚拟环境激活后我们就可以安全地安装Django了。这里不仅仅是运行一条安装命令我会带你理解版本选择并安装一些能极大提升开发体验的周边工具。4.1 安装Django版本选择与命令使用pip安装最新稳定版的Django非常简单pip install django但是在生产环境中直接安装最新版可能有风险。更专业的做法是指定一个具体版本以确保环境的一致性。你可以先查看有哪些版本pip index versions django假设我们选择安装Django 4.2.11一个长期支持版本LTSpip install django4.2.11为什么选择LTS版本LTS版本会获得更长时间的安全更新和支持通常3年对于需要长期维护的项目来说至关重要。非LTS版本的支持期可能只有8个月。安装完成后验证一下python -m django --version # 或 django-admin --version # 应输出4.2.11如果django-admin命令找不到请检查虚拟环境是否已激活。在虚拟环境下django-admin脚本会被安装到venv/bin/目录下。4.2 强烈推荐一同安装的开发效率工具仅仅安装Django还不够以下几个工具能让你在Mac上的Django开发如虎添翼建议在项目初期就一并安装。ipython一个增强的Python交互式Shell支持自动补全、语法高亮、内省等功能比原生的python manage.py shell好用太多。pip install ipython之后在Django项目中运行python manage.py shell它会自动使用IPython。django-extensions一个功能强大的Django第三方扩展集合提供了诸如shell_plus自动导入所有模型、runserver_plus带调试器的服务器、graph_models生成模型关系图等神器。pip install django-extensions安装后需要将其添加到项目的settings.py的INSTALLED_APPS中。black 与 isort代码格式化工具。black是“不妥协的代码格式化器”能自动将你的代码格式化成统一的风格isort则专门用于对import语句进行排序和分组。它们能让你从代码风格的争论中解放出来。pip install black isortpsycopg2-binary如果你计划使用PostgreSQL数据库生产环境推荐需要安装这个适配器。即使暂时不用先装上也无妨。pip install psycopg2-binary4.3 冻结依赖生成requirements.txt这是一个至关重要的步骤。requirements.txt文件记录了当前项目所有依赖包及其精确版本是项目可复现性的保证。 在虚拟环境激活的状态下运行pip freeze requirements.txt查看生成的requirements.txt文件你会看到类似这样的内容asgiref3.7.2 black23.11.0 django4.2.11 ...最佳实践将这个文件纳入版本控制如Git。当你的同事克隆项目或者你在新机器上部署时只需要创建虚拟环境然后运行pip install -r requirements.txt就能一键重建完全相同的依赖环境。5. 创建第一个Django项目并验证安装环境与工具都已就绪现在让我们真正启动一个Django项目验证一切是否工作正常。5.1 使用django-admin创建项目确保你在项目目录~/Projects/myblog下并且虚拟环境已激活。然后执行django-admin startproject myblog_project .注意命令最后的那个点.它表示在当前目录创建项目文件。如果不加点Django会再创建一个名为myblog_project的子目录。执行后你的目录结构应该如下myblog/ ├── venv/ # 虚拟环境目录 ├── manage.py # Django项目管理脚本 ├── myblog_project/ # 项目配置目录 │ ├── __init__.py │ ├── settings.py # 项目设置文件非常重要 │ ├── urls.py # 项目URL声明 │ └── wsgi.py # WSGI Web服务器接口 └── requirements.txt # 依赖列表5.2 初步配置与数据库迁移在启动服务器前我们最好先对settings.py做一点安全调整并初始化数据库。修改ALLOWED_HOSTS针对开发 打开myblog_project/settings.py找到ALLOWED_HOSTS。在开发阶段我们可以暂时允许所有主机或者添加本地地址ALLOWED_HOSTS [*] # 开发时可临时这样设置生产环境绝不允许 # 或更安全的方式 # ALLOWED_HOSTS [localhost, 127.0.0.1]执行数据库迁移 Django默认使用轻量级的SQLite数据库无需额外配置。我们需要运行迁移命令来创建数据库文件和应用所需的数据表python manage.py migrate这个命令会根据settings.py中INSTALLED_APPS的默认应用在项目根目录生成一个db.sqlite3文件并创建相应的表。5.3 启动开发服务器并访问Django自带一个轻量级的Web服务器专为开发设计。运行python manage.py runserver你会看到类似这样的输出Watching for file changes with StatReloader Performing system checks... System check identified no issues (0 silenced). December 07, 2023 - 10:00:00 Django version 4.2.11, using settings myblog_project.settings Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.现在打开你的Mac上的浏览器Safari, Chrome等访问http://127.0.0.1:8000/。你应该能看到Django的“火箭”欢迎页面上面写着“The install worked successfully! Congratulations!”恭喜这标志着你的Django环境在Mac上已成功安装并运行。6. 进阶配置与开发环境优化基础环境搭好了但要想开发得顺手还需要一些优化。这部分是针对Mac环境的一些贴心设置。6.1 配置Django使用自带的SQLite3避免系统版本问题macOS自带的SQLite3版本可能较旧。虽然Python安装时通常包含了SQLite3但为了确保一致性Django会使用Python模块中的sqlite3。一般情况下这没问题。如果你遇到数据库相关错误可以显式地告诉Django使用我们Python环境中的模块。在settings.py的DATABASES配置中其实无需额外配置因为它默认使用的就是Python的sqlite3模块。但你可以通过以下命令验证python -c import sqlite3; print(sqlite3.sqlite_version)这个版本号应该与你安装的Python版本捆绑的SQLite一致。6.2 使用django-extensions的增强功能还记得我们安装的django-extensions吗现在来配置它。编辑myblog_project/settings.py找到INSTALLED_APPS列表在最后添加INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, ... # 其他默认应用 django_extensions, # 添加这一行 ]现在你可以体验它的强大功能了超级增强的Shell运行python manage.py shell_plus它会自动导入你项目中所有的模型让你在调试时省去大量import语句。带Werkzeug调试器的Runserver运行python manage.py runserver_plus如果出现服务器错误页面会显示一个交互式的调试器可以直接在浏览器中执行代码片段来排查问题注意仅限开发环境生产环境禁用。6.3 设置环境变量与敏感信息管理永远不要将密码、密钥等敏感信息硬编码在settings.py里并提交到代码仓库。推荐使用环境变量。在Mac上我们可以在虚拟环境激活脚本中设置或者使用.env文件配合python-dotenv库。安装python-dotenvpip install python-dotenv在项目根目录manage.py同级创建.env文件touch .env在.env文件中定义你的密钥使用一个随机生成的字符串SECRET_KEYyour-super-secret-random-key-here-make-it-very-long DEBUGTrue修改myblog_project/settings.py顶部读取环境变量import os from pathlib import Path from dotenv import load_dotenv # 加载.env文件 load_dotenv() # Build paths inside the project like this: BASE_DIR / subdir. BASE_DIR Path(__file__).resolve().parent.parent # SECURITY WARNING: keep the secret key used in production secret! SECRET_KEY os.getenv(SECRET_KEY, a-default-fallback-key-for-dev-only) # SECURITY WARNING: dont run with debug turned on in production! DEBUG os.getenv(DEBUG, False) True至关重要将.env添加到你的.gitignore文件中确保它不会被提交。6.4 集成VS Code可选但推荐如果你使用VS Code可以配置一个高效的工作区。在项目根目录创建.vscode/settings.json{ python.defaultInterpreterPath: ${workspaceFolder}/venv/bin/python, python.linting.enabled: true, python.formatting.provider: black, python.formatting.blackArgs: [--line-length, 88], [python]: { editor.formatOnSave: true, editor.codeActionsOnSave: { source.organizeImports: true } }, files.exclude: { **/__pycache__: true, **/*.pyc: true, **/.pytest_cache: true, **/.venv: true } }安装VS Code的Python扩展。打开项目时VS Code会自动检测到虚拟环境venv并提示你选择它作为解释器。选择后所有代码补全、调试、格式化保存时自动用black格式化并用isort整理imports都会基于这个环境进行。7. 常见问题排查与解决方案即使按照教程一步步来你也可能会遇到一些“特色”问题。这里我汇总了几个在Mac上安装Django时的高频坑点。7.1 “zsh: command not found: python” 或 “python: command not found”问题在终端输入python或python3提示找不到命令。原因pyenv没有正确初始化或者其shims目录不在PATH中。解决确认已按照步骤2.3将pyenv init的配置添加到~/.zshrc并执行了source ~/.zshrc。检查PATHecho $PATH查看是否有/Users/你的用户名/.pyenv/shims路径。尝试完全重启终端或者新开一个终端标签页。7.2 “Error: The ‘sqlite3’ module is not available.”问题运行python manage.py migrate时提示缺少sqlite3模块。原因通过pyenv编译安装Python时可能缺少SQLite3的开发头文件。解决确保已通过Homebrew安装了sqlite3brew install sqlite3重新安装Python并在安装前指定sqlite3的路径。首先找到sqlite3的安装路径brew --prefix sqlite3 # 输出类似/opt/homebrew/opt/sqlite3使用PYTHON_CONFIGURE_OPTS环境变量重新安装PythonPYTHON_CONFIGURE_OPTS--with-sqlite3-libs$(brew --prefix sqlite3)/lib --with-sqlite3-includes$(brew --prefix sqlite3)/include pyenv install 3.11.97.3 “django-admin: command not found”问题创建项目时找不到django-admin命令。原因99%的情况是没有激活虚拟环境。Django被安装在了虚拟环境的bin目录下全局路径中没有。解决确保你已进入项目目录。运行source venv/bin/activate激活虚拟环境。再运行django-admin startproject ...。7.4 端口8000被占用问题运行runserver时提示Error: That port is already in use.解决可以指定另一个端口运行服务器例如使用8080端口python manage.py runserver 8080然后访问http://127.0.0.1:8080/。7.5 安装包速度慢或超时问题pip install时下载速度极慢甚至超时。原因默认的PyPI源在国外。解决为pip配置国内镜像源。在虚拟环境下创建或编辑~/.pip/pip.conf文件Mac用户内容如下[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn或者在安装时临时指定源pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple8. 从安装到上手创建你的第一个应用环境彻底搞定后让我们快速走一遍Django的标准工作流感受一下它的魅力。8.1 创建应用App在Django中项目Project是网站的配置集合而应用App是一个实现具体功能的Web应用。一个项目可以包含多个应用。 在项目根目录有manage.py的目录下运行python manage.py startapp articles这会创建一个名为articles的应用目录里面包含了模型models.py、视图views.py等文件。8.2 定义模型并激活应用编辑articles/models.py创建一个简单的文章模型from django.db import models class Article(models.Model): title models.CharField(max_length200) content models.TextField() created_at models.DateTimeField(auto_now_addTrue) updated_at models.DateTimeField(auto_nowTrue) def __str__(self): return self.title然后将articles应用添加到项目配置中。编辑myblog_project/settings.py的INSTALLED_APPS列表INSTALLED_APPS [ ..., articles, # 添加这一行 ]8.3 创建并应用数据库迁移每当你更改了模型models.py就需要创建迁移文件来记录这些更改然后应用到数据库。生成迁移文件python manage.py makemigrations articles这会在articles/migrations/目录下生成一个类似0001_initial.py的文件。应用迁移更新数据库python manage.py migrate8.4 创建超级用户并探索Admin后台Django的一大亮点是其自动生成的管理后台。首先我们需要创建一个可以登录后台的超级用户python manage.py createsuperuser按提示输入用户名、邮箱和密码。然后确保articles应用在后台可见。编辑articles/admin.pyfrom django.contrib import admin from .models import Article admin.site.register(Article)现在启动开发服务器如果已停止python manage.py runserver访问http://127.0.0.1:8000/admin/用刚才创建的超级用户登录。你应该能看到“Articles”模型并可以对其进行增删改查操作。至此你已经完成了一个具备完整CRUD功能的Django应用雏形。整个过程从安装Python、Django到创建项目、应用、模型再到生成管理后台Django的“电池内置”哲学体现得淋漓尽致。在Mac上搭建好这个稳固的环境只是你Django之旅的起点。接下来你可以深入探索视图Views、URL路由URLs、模板Templates来构建前端页面或者研究Django REST Framework来构建API。记住良好的开端是成功的一半现在你的Mac已经拥有了一个专业、隔离且高效的Django开发环境可以放心地去构建任何你想做的Web应用了。如果在后续开发中遇到环境问题随时回看这篇指南中关于pyenv和虚拟环境的部分它们是你保持环境清爽的基石。