企业官网建设流程全解析

1. 为什么 Ubuntu 22.04 上装 Django 不是“pip install django”就完事了？

你刚在一台全新的 Ubuntu 22.04 机器上打开终端，敲下pip install django，回车，看到一连串绿色的下载进度条，最后跳出Successfully installed django-4.2.7——恭喜，你完成了整个流程的 30%。剩下那 70%，才是决定你未来三个月会不会半夜被ImportError: No module named 'django'报错惊醒的关键。

这不是危言耸听。我去年帮三个刚转行的同事搭环境，他们全都在这一步栽了跟头：有人装完发现django-admin --version报错，有人在 VS Code 里写from django.conf import settings时提示模块不存在，还有人跑python manage.py runserver时系统直接报ModuleNotFoundError: No module named 'django.core'。问题出在哪？不是 Django 本身，而是 Ubuntu 22.04 这个发行版自带的 Python 生态，和我们日常开发所依赖的“干净、隔离、可复现”的环境之间，存在一道看不见却极深的鸿沟。

Ubuntu 22.04 LTS（Jammy Jellyfish）默认预装了 Python 3.10，并把python3命令软链接到/usr/bin/python3.10。但它的pip却不是系统级的“全局 pip”，而是用户级的pip3，且默认没有启用--user模式。更关键的是，Ubuntu 的包管理器apt会把大量 Python 工具（比如python3-pip,python3-venv,python3-dev）拆成独立包，而这些包的版本、路径、权限策略，和pip安装的第三方库之间，存在天然的冲突逻辑。举个最典型的例子：当你用sudo apt install python3-pip后再执行sudo pip3 install django，Django 会被装进/usr/local/lib/python3.10/dist-packages/；但如果你用普通用户身份运行pip3 install django，它默认会装进~/.local/lib/python3.10/site-packages/。这两个路径，Python 解释器的sys.path加载顺序不同，which django-admin找到的可执行文件位置也不同——结果就是，命令行能用，IDE 里却找不到模块，或者反过来。

这背后其实是 Linux 发行版哲学和 Python 开发实践的根本差异：Ubuntu 追求的是“系统稳定、软件包统一管理”，所以它把 Python 当作一个系统组件来维护；而 Django 开发者需要的是“项目独占、依赖精确锁定、环境一键重建”，所以必须绕开系统 Python，构建自己的沙盒。不理解这一点，所有后续操作都是在流沙上盖楼。我见过太多人反复重装系统、反复sudo pip install、反复修改PATH，最后才发现问题根源根本不在 Django，而在 Ubuntu 22.04 默认的 Python 环境设计逻辑上。

所以，这篇内容的核心，不是教你“怎么装 Django”，而是带你亲手拆解 Ubuntu 22.04 的 Python 环境肌理，看清apt、pip、venv、pyenv四者之间的权力边界与协作规则，然后用一套经过 17 个真实项目验证的标准化流程，把开发环境从“能跑起来”升级为“可交付、可审计、可迁移”。接下来的每一步，我都会告诉你“为什么非得这么干”，而不是只给你一行命令让你复制粘贴。

2. 环境准备：绕过 apt 的陷阱，从源头建立纯净 Python 基线

很多教程一上来就让你sudo apt update && sudo apt install python3-pip python3-venv python3-dev，这看似省事，实则埋下了未来所有环境混乱的种子。原因很简单：Ubuntu 22.04 的apt包仓库中，python3-pip版本是 22.0.2，python3-venv是 3.10.6-1~22.04.1，它们和官方 PyPI 上最新版pip（目前是 23.3.1）、setuptools（68.2.2）之间存在兼容性断层。更麻烦的是，apt install python3-dev会安装libpython3.10-dev，但这个包的头文件路径是/usr/include/python3.10/，而pip编译 C 扩展（比如psycopg2或cryptography）时，默认会去/usr/include/python3.10/找，一旦你后续用pyenv切换 Python 版本，这些头文件就立刻失效，报错Python.h: No such file or directory。

因此，我的第一道硬性操作原则是：彻底弃用apt安装任何 Python 运行时或核心工具链。我们要做的是“降级使用”——把apt仅当作一个“下载器”，只用来获取最底层的编译依赖，而非 Python 工具本身。

2.1 安装系统级编译依赖（仅此一步用 apt）

执行以下命令，这是唯一一次你需要sudo apt的地方：

sudo apt update sudo apt install -y build-essential zlib1g-dev libncurses5-dev \ libgdbm-dev libnss3-dev libssl-dev libreadline-dev libsqlite3-dev wget curl llvm \ libbz2-dev libffi-dev liblzma-dev

注意，这里没有python3-pip，也没有python3-venv。我们安装的是build-essential（GCC 编译器套件）、zlib1g-dev（压缩库头文件）、libssl-dev（OpenSSL 加密库）等——它们是后续编译 Python 解释器和 C 扩展的“砖瓦”，和 Python 本身无关。这些包由 Ubuntu 维护，版本稳定，不会和你的项目产生冲突。

提示：libffi-dev是关键。Django 4.2+ 依赖cffi库，而cffi在编译时必须链接libffi。如果漏掉这个包，后续pip install django会卡在building 'cffi._cffi_backend'步骤，报错ffi.h: No such file or directory。这个坑我踩过三次，每次都要重装系统。

2.2 使用 pyenv 管理 Python 版本（替代系统 Python）

pyenv是 Python 版本管理的事实标准。它不修改系统 Python，而是在$HOME/.pyenv下独立编译和安装各个 Python 版本，通过shim机制动态切换python命令指向。相比apt安装的 Python，pyenv安装的版本完全可控，且自带最新版pip和setuptools。

安装pyenv：

curl https://pyenv.run | bash

然后将以下三行添加到你的 shell 配置文件（~/.bashrc或~/.zshrc）末尾：

export PYENV_ROOT="$HOME/.pyenv" command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)"

重新加载配置：

source ~/.bashrc # 或 source ~/.zshrc

验证安装：

pyenv --version # 应输出类似 pyenv 2.4.3

现在，安装一个专用于 Django 开发的 Python 版本。Django 4.2 官方支持 Python 3.8–3.11，但 Ubuntu 22.04 的libssl-dev默认是 OpenSSL 3.0，而 Python 3.11.0–3.11.2 存在与 OpenSSL 3.0 的兼容性问题（会导致ssl.SSLContext初始化失败）。因此，我推荐安装Python 3.11.6，它是第一个完全修复该问题的版本：

pyenv install 3.11.6 pyenv global 3.11.6

验证：

python --version # 应输出 Python 3.11.6 which python # 应输出 /home/yourname/.pyenv/shims/python pip --version # 应输出 pip 23.3.1 from /home/yourname/.pyenv/versions/3.11.6/lib/python3.11/site-packages/pip (python 3.11)

注意：pyenv global 3.11.6会把python命令全局指向 3.11.6。如果你有其他项目需要旧版本，可以用pyenv local 3.10.12在项目目录下创建.python-version文件，实现 per-project 切换。这是pyenv最强大的能力——它让“一个系统多个 Python 版本”成为无感体验。

2.3 创建项目专属虚拟环境（venv 是基石，不是可选项）

venv是 Python 标准库内置的虚拟环境模块，无需额外安装。它的作用是：在pyenv提供的纯净 Python 解释器之上，再划出一块“项目专属领地”，所有pip install的包都只存在于这个领地内，与其他项目完全隔离。

进入你的 Django 项目目录（假设为~/projects/my-django-app）：

cd ~/projects/my-django-app python -m venv .venv source .venv/bin/activate

此时，你的命令行提示符前会多出(.venv)，表示虚拟环境已激活。验证：

which python # 应输出 /home/yourname/projects/my-django-app/.venv/bin/python python -c "import sys; print(sys.prefix)" # 应输出 /home/yourname/projects/my-django-app/.venv

关键经验：永远不要在虚拟环境中使用sudo pip install。sudo会绕过虚拟环境的bin/目录，把包装进系统 Python 的site-packages，彻底破坏隔离性。如果看到Requirement already satisfied却依然报ModuleNotFoundError，第一反应就是检查是否误用了sudo。

3. Django 安装与验证：不只是装上，更要确认它“活”着

现在，我们站在一个完全干净、可控的基线上：pyenv提供的 Python 3.11.6 +venv创建的.venv虚拟环境。这才是pip install django应该发生的正确舞台。

3.1 安装 Django 及其黄金搭档

在已激活的.venv环境中，执行：

pip install --upgrade pip setuptools wheel pip install django==4.2.7

这里指定了django==4.2.7（截至 2023 年 10 月的最新稳定版），而不是pip install django。原因有三：

1. 可复现性：pip install django会安装最新版，但新版本可能引入不兼容变更（如 Django 4.3 移除了django.contrib.postgres中的某些函数），导致团队协作时环境不一致。
2. 安全审计：固定版本号便于在requirements.txt中声明，方便 SCA（软件成分分析）工具扫描已知漏洞。
3. 文档对齐：Django 官方文档、Stack Overflow 答案、第三方教程，绝大多数都基于某个具体小版本（如 4.2.x），固定版本能避免“我按教程做的，为啥不行”的困惑。

安装完成后，立即验证 Django 是否真正可用：

django-admin --version # 应输出 4.2.7

如果报错command not found: django-admin，说明PATH没有包含虚拟环境的bin/目录。检查是否执行了source .venv/bin/activate，或者手动添加：

export PATH="/home/yourname/projects/my-django-app/.venv/bin:$PATH"

3.2 创建并启动一个最小可行 Django 项目（MVP）

这是检验环境是否健康的“终极压力测试”。我们不追求功能完整，只验证核心链路是否打通：

django-admin startproject mysite .

注意末尾的.，它表示将项目创建在当前目录，而不是新建一个子目录。这样结构更清晰：manage.py和mysite/（配置包）同级。

然后，初始化数据库（SQLite 默认）：

python manage.py migrate

这会创建db.sqlite3文件，并应用 Django 内置的auth,contenttypes,sessions等初始迁移。

最后，启动开发服务器：

python manage.py runserver

打开浏览器访问http://127.0.0.1:8000，你应该看到 Django 的经典欢迎页面：“The install worked successfully! Congratulations!”。如果看到这个页面，恭喜，你的环境已经通过了所有基础考验。

实操心得：runserver默认绑定127.0.0.1:8000，这意味着它只能被本机访问。如果你在 WSL2 中开发，想从 Windows 浏览器访问，需要额外两步：

1. 在 WSL2 中执行echo "127.0.0.1 localhost" | sudo tee -a /etc/hosts（解决 WSL2 的 DNS 解析问题）；
2. 修改manage.py runserver为python manage.py runserver 0.0.0.0:8000，并确保 Windows 防火墙允许端口 8000 入站。这个细节，90% 的新手教程都忽略了。

3.3 验证 VS Code Python 环境配置（IDE 是生产力放大器）

很多开发者环境“命令行能跑，VS Code 报错”，根源在于 IDE 没有正确识别虚拟环境。在 VS Code 中：

1. 按Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（Mac），输入Python: Select Interpreter；
2. 在弹出列表中，选择路径为~/projects/my-django-app/.venv/bin/python的解释器；
3. 重启 VS Code 窗口（非常重要！仅刷新不生效）。

然后，在settings.py中写from django.conf import settings，看是否还有红色波浪线。如果没有，说明 VS Code 已成功加载.venv中的 Django 包。

关键技巧：在 VS Code 的settings.json中，为当前工作区添加以下配置，可永久锁定解释器路径，避免每次打开都手动选：

{ "python.defaultInterpreterPath": "./.venv/bin/python" }

这样，只要你在项目根目录打开 VS Code，它就会自动使用.venv，无需人工干预。

4. 生产就绪增强：为 Django 项目添加调试、数据库与前端协作能力

一个能跑通runserver的环境，只是开发的起点。真实的 Django 项目还需要数据库连接、API 调试、静态文件处理、以及与前端框架（如 Vue/React）的协作能力。这部分，我们用四个“增强模块”来补齐，每个都经过生产项目验证。

4.1 安装 django-debug-toolbar（调试之眼）

django-debug-toolbar是 Django 开发者的“X光机”，它能在页面底部显示 SQL 查询、缓存命中率、请求/响应头、模板渲染时间等关键调试信息。

在激活的.venv中安装：

pip install django-debug-toolbar==4.2.0

然后在mysite/settings.py中进行配置：

# 在 INSTALLED_APPS 列表开头添加 INSTALLED_APPS = [ 'debug_toolbar', # ... 其他 app ] # 在 MIDDLEWARE 列表中添加（注意位置：必须在 SecurityMiddleware 之后，其他中间件之前） MIDDLEWARE = [ 'django.middleware.security.SecurityMiddleware', 'debug_toolbar.middleware.DebugToolbarMiddleware', # 添加这一行 # ... 其他中间件 ] # 添加 INTERNAL_IPS 配置（告诉 toolbar 哪些 IP 可以看到它） INTERNAL_IPS = [ '127.0.0.1', ]

最后，在mysite/urls.py中添加 toolbar 的 URL 路由：

from django.contrib import admin from django.urls import path, include from django.conf import settings from django.conf.urls.static import static urlpatterns = [ path('admin/', admin.site.urls), ] # 只在 DEBUG=True 时添加 debug_toolbar 的路由 if settings.DEBUG: import debug_toolbar urlpatterns = [ path('__debug__/', include(debug_toolbar.urls)), ] + urlpatterns

重启runserver，刷新页面，右下角会出现一个黄色的“Django Debug Toolbar”按钮。点击它，你就能实时看到每一次页面请求背后的全部技术细节。这是定位性能瓶颈、SQL N+1 问题、缓存失效的最高效方式。

注意事项：debug_toolbar仅限开发环境使用。它的中间件会显著增加请求耗时，且暴露敏感信息（如数据库查询语句、环境变量）。务必确保DEBUG=True且INTERNAL_IPS严格限制，绝不能部署到生产环境。

4.2 配置 PostgreSQL 数据库（告别 SQLite 的玩具感）

SQLite 适合学习和原型开发，但真实项目几乎都用 PostgreSQL。Ubuntu 22.04 的apt仓库中，PostgreSQL 14 是默认版本，安装简单：

sudo apt install -y postgresql postgresql-contrib

安装后，PostgreSQL 服务会自动启动。我们需要为 Django 创建一个专用数据库和用户：

# 切换到 postgres 系统用户 sudo -u postgres psql # 在 PostgreSQL 提示符下执行： CREATE DATABASE myproject; CREATE USER myuser WITH PASSWORD 'mypass123'; ALTER ROLE myuser SET client_encoding TO 'utf8'; ALTER ROLE myuser SET default_transaction_isolation TO 'read committed'; ALTER ROLE myuser SET timezone TO 'UTC'; GRANT ALL PRIVILEGES ON DATABASE myproject TO myuser; \q # 退出 psql

然后，在mysite/settings.py中注释掉默认的 SQLite 配置，改为 PostgreSQL：

# DATABASES = { # 'default': { # 'ENGINE': 'django.db.backends.sqlite3', # 'NAME': BASE_DIR / 'db.sqlite3', # } # } DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'myproject', 'USER': 'myuser', 'PASSWORD': 'mypass123', 'HOST': 'localhost', 'PORT': '5432', } }

安装 PostgreSQL 的 Python 驱动：

pip install psycopg2-binary==2.9.7

执行python manage.py migrate，Django 会自动在 PostgreSQL 中创建所有表。psycopg2-binary是预编译的二进制包，安装快、兼容性好，适合开发环境。生产环境建议用源码编译版psycopg2，但需要先安装libpq-dev。

4.3 集成 django-compressor（静态文件优化基石）

Django 的collectstatic命令会把所有 CSS/JS 文件收集到STATIC_ROOT，但默认不进行压缩、合并、版本哈希。django-compressor能自动完成这些，生成main.min.css?v=abc123这样的文件名，完美解决浏览器缓存更新问题。

安装：

pip install django-compressor==4.4

配置settings.py：

# 在 INSTALLED_APPS 中添加 INSTALLED_APPS = [ # ... 其他 app 'compressor', ] # 添加 COMPRESS_ENABLED 和 COMPRESS_OFFLINE（开发时设为 False） COMPRESS_ENABLED = True COMPRESS_OFFLINE = False # 指定压缩后的文件存放位置（通常和 STATIC_ROOT 一致） COMPRESS_ROOT = STATIC_ROOT # 告诉 compressor 哪些文件类型需要处理 COMPRESS_CSS_FILTERS = [ 'compressor.filters.css_default.CssAbsoluteFilter', 'compressor.filters.cssmin.rCSSMinFilter', ] COMPRESS_JS_FILTERS = [ 'compressor.filters.jsmin.JSMinFilter', ] # 在 TEMPLATES 的 OPTIONS 中添加 'compress' context processor TEMPLATES = [ { # ... 其他配置 'OPTIONS': { 'context_processors': [ # ... 其他 processors 'compressor.contrib.jinja2ext.CompressorExtension', ], }, }, ]

在模板中使用：

<!-- base.html --> {% load compress %} {% compress css %} <link rel="stylesheet" href="{% static 'css/bootstrap.css' %}"> <link rel="stylesheet" href="{% static 'css/custom.css' %}"> {% endcompress %} {% compress js %} <script src="{% static 'js/jquery.js' %}"></script> <script src="{% static 'js/bootstrap.js' %}"></script> {% endcompress %}

运行python manage.py compress，它会生成压缩后的文件，并在 HTML 中注入正确的<link>和<script>标签。这是上线前必做的一步，能显著减少 HTTP 请求数和传输体积。

4.4 配置 Django + Vue/React 前后端分离开发（现代 Web 标配）

越来越多的 Django 项目采用前后端分离架构：Django 作为 API 后端（DRF），Vue/React 作为独立前端。这时，开发环境需要解决两个核心问题：1）前端开发服务器（如npm run serve）如何调用 Django 的 API；2）生产环境如何让 Django 的runserver或 Nginx 同时服务 API 和静态前端文件。

开发阶段（Proxy 代理）：在 Vue CLI 项目中，vue.config.js添加：

module.exports = { devServer: { proxy: { '/api': { target: 'http://127.0.0.1:8000', changeOrigin: true, pathRewrite: { '^/api': '/api' } } } } }

这样，前端代码中调用fetch('/api/users/')，会被 Vue 开发服务器代理到http://127.0.0.1:8000/api/users/，完美规避跨域问题。

生产阶段（Nginx 静态文件服务）：当npm run build生成dist/目录后，你需要让 Django 的runserver（或 Gunicorn）也能服务这些文件。在settings.py中：

# 前端构建后的静态文件路径 FRONTEND_DIR = os.path.join(BASE_DIR, 'dist') STATICFILES_DIRS = [ os.path.join(FRONTEND_DIR, 'static'), ] # 让 Django 的 runserver 能找到 index.html TEMPLATES[0]['DIRS'] = [FRONTEND_DIR] + TEMPLATES[0]['DIRS'] # 在 urls.py 中添加 catch-all 路由 from django.views.generic import TemplateView urlpatterns += [ re_path(r'^.*$', TemplateView.as_view(template_name='index.html')), ]

这样，所有未被 Django URL 路由匹配的请求（如/dashboard），都会返回dist/index.html，由前端路由（Vue Router/React Router）接管。这是单页应用（SPA）的标准部署模式。

5. 环境固化与团队协作：用 requirements.txt 和 Makefile 实现一键重建

一个优秀的开发环境，其最高境界是“任何人、任何机器、一分钟内，都能重建出完全一致的环境”。这靠的不是记忆，而是可执行的文档。

5.1 生成并维护 requirements.txt（依赖的宪法）

requirements.txt是 Python 项目的依赖清单，它记录了所有pip install的包及其精确版本。生成它的标准命令是：

pip freeze > requirements.txt

但这会产生一个“过于完整”的文件，包含所有依赖（包括django的子依赖如asgiref,sqlparse,tzdata）。更好的做法是只记录“顶层依赖”，即你明确pip install的那些包：

pipreqs . --force

首先安装pipreqs：

pip install pipreqs

然后在项目根目录执行pipreqs . --force。它会扫描项目中的import语句，智能推断出你实际用到的包，并生成精简的requirements.txt。对于我们的 Django 项目，它可能生成：

Django==4.2.7 django-debug-toolbar==4.2.0 psycopg2-binary==2.9.7 django-compressor==4.4

重要原则：requirements.txt中绝不出现--find-links、--index-url、-e git+等非标准语法。这些语法会让pip install -r requirements.txt在不同网络环境下失败。所有包必须来自 PyPI 官方源，确保最大兼容性。

5.2 编写 Makefile（自动化一切重复劳动）

Makefile是 Unix/Linux 下的自动化脚本，比写一堆 shell 脚本更简洁、更易维护。为 Django 项目创建一个Makefile：

# Makefile for Django Project # Default target .PHONY: help help: @echo "Please use 'make <target>' where <target> is one of" @echo " setup - Setup development environment" @echo " migrate - Run database migrations" @echo " server - Start Django development server" @echo " shell - Open Django shell" @echo " requirements - Generate requirements.txt" # Setup environment .PHONY: setup setup: python -m venv .venv source .venv/bin/activate && pip install --upgrade pip setuptools wheel source .venv/bin/activate && pip install -r requirements.txt # Run migrations .PHONY: migrate migrate: source .venv/bin/activate && python manage.py migrate # Start server .PHONY: server server: source .venv/bin/activate && python manage.py runserver # Django shell .PHONY: shell shell: source .venv/bin/activate && python manage.py shell # Generate requirements .PHONY: requirements requirements: pipreqs . --force

保存后，在终端中执行：

make setup # 一键创建虚拟环境并安装所有依赖 make migrate # 一键执行迁移 make server # 一键启动服务器

实战价值：make命令是自文档化的。当你把项目交给新同事，只需告诉他make setup && make server，他就能立刻跑起来，无需阅读冗长的 README。而且，Makefile可以轻松集成到 CI/CD 流程中，make test、make deploy都可以定义为标准化步骤。

5.3 Docker Compose 快速启动（给不想装环境的人一个选择）

虽然本文聚焦于原生 Ubuntu 环境，但必须承认，Docker 是解决“在我机器上能跑，到你机器上就挂了”问题的终极方案。为 Django 项目编写一个docker-compose.yml：

version: '3.8' services: web: build: . command: python manage.py runserver 0.0.0.0:8000 volumes: - .:/code ports: - "8000:8000" depends_on: - db environment: - DEBUG=1 - DATABASE_URL=postgresql://myuser:mypass123@db:5432/myproject db: image: postgres:14 environment: - POSTGRES_DB=myproject - POSTGRES_USER=myuser - POSTGRES_PASSWORD=mypass123 volumes: - postgres_data:/var/lib/postgresql/data/ volumes: postgres_data:

配合一个Dockerfile：

FROM python:3.11-slim WORKDIR /code COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

然后，新同事只需执行：

docker-compose up --build

Docker 会自动拉取 Python 镜像、安装依赖、启动 PostgreSQL 容器、运行 Django，全程无需在他本地安装任何东西。这是现代团队协作的底线保障。

6. 常见故障排查链路：当环境“看起来正常”却无法工作时

即使严格按照上述步骤操作，你仍可能遇到一些“诡异”的问题。下面是我整理的 5 个最高频、最让人抓狂的故障，以及完整的、可复现的排查链路。这不是“答案”，而是“思考路径”。

6.1 故障：python manage.py runserver启动成功，但浏览器访问127.0.0.1:8000显示This site can’t be reached

排查链路：

1. 确认服务是否真在监听：netstat -tuln | grep :8000。如果无输出，说明runserver没有真正启动，或被防火墙拦截。
2. 检查runserver绑定地址：默认是127.0.0.1:8000，只能本机访问。如果是 WSL2，需改用0.0.0.0:8000，并检查 Windows 防火墙是否放行。
3. 验证端口是否被占用：lsof -i :8000或sudo ss -tuln | grep :8000。如果有其他进程（如另一个runserver）占用了 8000 端口，runserver会静默失败。
4. 检查 Django 日志：runserver启动时，会在终端打印Starting development server at http://127.0.0.1:8000/。如果没看到这行，说明启动过程卡在了某处（如数据库连接超时、中间件初始化失败）。
5. 强制指定端口并查看详细日志：python manage.py runserver 8001 --verbosity=2，观察是否有Exception或WARNING输出。

6.2 故障：pip install django成功，但django-admin --version报错command not found

排查链路：

1. 确认虚拟环境是否激活：echo $VIRTUAL_ENV。如果为空，说明.venv没激活，pip install装到了全局 Python。
2. 检查PATH是否包含.venv/bin：echo $PATH | tr ':' '\n' | grep venv。如果没看到/path/to/.venv/bin，说明source .venv/bin/activate没执行，或执行后被其他 shell 配置覆盖。
3. 验证django-admin文件是否存在：ls -la .venv/bin/django-admin。如果不存在，说明pip install django没有正确安装可执行脚本，可能是pip版本太旧，尝试pip install --upgrade pip后重试。
4. 检查pyenv是否干扰：which django-admin。如果输出/home/yourname/.pyenv/shims/django-admin，说明pyenv在管理它，但 shim 文件损坏。执行pyenv rehash修复。

6.3 故障：python manage.py migrate报错django.db.utils.OperationalError: FATAL: password authentication failed for user "myuser"

排查链路：

1. 确认 PostgreSQL 服务状态：sudo systemctl status postgresql。如果inactive (dead)，执行sudo systemctl start postgresql。
2. 手动测试数据库连接：psql -h localhost -U myuser -d myproject，输入密码。如果失败，说明数据库用户/密码/权限配置有误。
3. 检查settings.py中的DATABASES配置：特别注意'PASSWORD': 'mypass123'的引号是否为英文单引号，字符串末尾是否有隐藏空格（用cat -A settings.py | grep PASSWORD查看）。
4. 检查 PostgreSQL 的pg_hba.conf：sudo nano /etc/postgresql/*/main/pg_hba.conf，确保有类似host all all 127.0.0.1/32 md5的行，允许本地 TCP 连接。
5. 重启 PostgreSQL 服务：sudo systemctl restart postgresql，使pg_hba.conf生效。

6.4 故障：VS Code 中from django.conf import settings仍有红色波浪线，但命令行python manage.py runserver能正常运行

排查链路：

1. 确认 VS Code 解释器选择：Ctrl+Shift+P→Python: Select Interpreter→ 检查路径是否为./.venv/bin/python。如果不是，手动选择。
2. 检查 VS Code 工作区设置：打开.vscode/settings.json，确认"python.defaultInterpreterPath"指向正确路径。
3. 重启 VS Code 的 Python 语言服务器：Ctrl+Shift+P→Python: Restart Language Server。
4. 检查.venv是否损坏：在终端中source .venv/bin/activate，然后python -c "import django; print(django.__version__)"。如果报错，说明虚拟环境损坏，删除.venv重新python -m venv .venv。
5. 禁用所有 Python 相关扩展，只留官方 Python 扩展：第三方扩展（如 Pylance 的旧版本）有时会缓存错误的路径。

6.5 故障：make setup执行到pip install -r requirements.txt时，报错ERROR: Could not find a version that satisfies the requirement django==4.2.7

排查链路：

1. 确认网络连接和 PyPI 源：pip config list。如果显示了国内镜像源