设置非根路径WSGIScriptAlias时Django项目出现404页面问题排查

环境信息 #

• Python 3.12.2
• Django 5.0.3
• Apache HTTPD 2.4.58
• Windows 11

项目目录结构 #

D:\dev\htdocs                 # Apache HTTPD DocumentRoot
├───...                       # 其他目录
│
└───nutrihub_pyvenv           # Django项目的虚拟环境容器
    ├───.venv                 # 使用pipenv管理虚拟环境
    │
    └───nutrihub
        │   db.sqlite3
        │   manage.py
        │   Pipfile
        │   Pipfile.lock
        │
        └───nutrihub
                asgi.py
                settings.py
                urls.py
                wsgi.py
                __init__.py

当前Apache配置 #

LoadFile "c:/Python312/python312.dll"
LoadModule wsgi_module "d:/dev/htdocs/nutrihub_pyvenv/.venv/Lib/site-packages/mod_wsgi/server/mod_wsgi.cp312-win_amd64.pyd"
    
WSGIScriptAlias /nhub "d:/dev/htdocs/nutrihub_pyvenv/nutrihub/nutrihub/wsgi.py"
WSGIPythonHome "d:/dev/htdocs/nutrihub_pyvenv/.venv"
WSGIPythonPath "d:/dev/htdocs/nutrihub_pyvenv/nutrihub;"
WSGIApplicationGroup %{GLOBAL}
<Directory "d:/dev/htdocs/nutrihub_pyvenv/nutrihub/">
  <Files "wsgi.py">
    Require all granted
  </Files>
</Directory>

当前Django settings.py部分配置 #

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

问题现象 #

• 执行py manage.py runserver后，访问http://localhost:8000/能看到成功提示页面；
• 启动Apache后访问http://localhost/nhub出现404错误，提示“空路径未匹配任何URL规则”；
• 将WSGIScriptAlias改为根路径/后，访问http://localhost则正常显示成功页面。

原因及解决办法 #

核心原因 #

当Apache配置WSGIScriptAlias /nhub时，所有以/nhub开头的请求会被转发给Django，且Django收到的是去掉前缀后的路径：访问/nhub等价于向Django请求根路径/。但刚创建的Django项目默认urls.py中只有/admin/的规则，没有匹配/的规则，因此返回404。而当WSGIScriptAlias设为/时，访问/触发的是Django DEBUG模式下的调试404页面（会列出可用URL），你误以为是“成功页面”。

解决步骤 #

1. 添加根路径URL规则（推荐）

在项目的nutrihub/urls.py中添加匹配根路径的规则，比如跳转到admin页面：

from django.contrib import admin
from django.urls import path
from django.views.generic.base import RedirectView

urlpatterns = [
    path('admin/', admin.site.urls),
    # 根路径自动跳转到admin后台
    path('', RedirectView.as_view(pattern_name='admin:index', permanent=False)),
]

这样访问http://localhost/nhub会直接跳转到http://localhost/nhub/admin/，不再出现404。

2. 配置URL前缀（确保链接生成正确）

如果需要Django生成的所有内部链接（比如admin页面的导航链接）都自动带上/nhub前缀，在settings.py中添加：

FORCE_SCRIPT_NAME = '/nhub'

这个参数告诉Django它部署在/nhub子路径下，避免生成的链接丢失前缀。

3. 验证Apache配置

当前Apache配置已经正确设置了WSGIPythonPath和WSGIScriptAlias，无需调整，确保路径指向无误即可。

内容的提问来源于stack exchange，提问作者fishfin