如何调试Heroku上部署的Django应用？本地无法复现问题

一、使用PDB连接Web Dyno进行单步调试 #

这个方法适合你需要深入单步追踪请求流程的场景，但仅建议在测试/低流量环境使用，因为会暂时中断正常服务：

1. 插入断点：在你要调试的请求处理代码（比如视图函数、中间件）中加入：

   import pdb; pdb.set_trace()
   

2. 暂停正常Web Dyno：先停止当前运行的web dyno，避免请求被分流到其他实例：

   heroku ps:scale web=0
   

3. 启动交互式Web Dyno：用前台模式启动一个web dyno，这样pdb的交互会话会直接连接到你的本地终端：

   heroku run:web
   

   这个命令会根据你的Procfile启动web服务，并且保持终端的交互式状态。
4. 触发请求并调试：通过heroku open或者直接访问你的应用域名，触发包含断点的请求。此时你的本地终端会进入pdb交互界面，你可以用这些常用命令调试：
   • n：执行下一步
   • s：进入当前调用的函数
   • c：继续执行直到下一个断点
   • p 变量名：查看变量值
5. 恢复正常服务：调试完成后，记得删除代码中的pdb语句，然后恢复web dyno的正常运行：

   heroku ps:scale web=1
   

⚠️ 注意：这个交互式dyno是临时的，关闭终端就会终止，而且调试期间正常服务会中断，绝对不要在高流量生产环境这么做。

二、其他更实用的调试方案 #

如果不能中断服务，或者需要更高效的调试方式，这些方案会更合适：

1. 强化日志记录（最通用的线上调试方式） #

线上环境最安全的调试手段就是完善日志：

• 在Django的settings.py中配置更详细的日志，比如将日志级别设为DEBUG，记录请求参数、用户信息、堆栈跟踪：

  LOGGING = {
      'version': 1,
      'disable_existing_loggers': False,
      'handlers': {
          'console': {
              'class': 'logging.StreamHandler',
          },
      },
      'root': {
          'handlers': ['console'],
          'level': 'DEBUG',
      },
      'loggers': {
          'django': {
              'handlers': ['console'],
              'level': 'DEBUG',
              'propagate': False,
          },
      },
  }
  

• 在关键代码位置手动添加日志，比如：

  import logging
  logger = logging.getLogger(__name__)
  
  def my_view(request):
      logger.debug(f"Received request: {request.method} {request.path}")
      logger.debug(f"Request GET params: {request.GET}")
      logger.debug(f"User: {request.user.username if request.user.is_authenticated else 'Anonymous'}")
      # 后续代码
  

• 用heroku logs --tail命令实时查看线上日志，或者用heroku logs -n 1000查看最近的1000条日志。

2. 使用Debugpy进行远程IDE调试 #

比pdb更友好的远程调试方式，支持在本地IDE（比如VS Code、PyCharm）中直接调试线上代码：

1. 在requirements.txt中添加debugpy，部署到Heroku。
2. 在Django的wsgi.py或asgi.py开头添加调试代码：

   import debugpy
   # 监听所有IP的5678端口
   debugpy.listen(("0.0.0.0", 5678))
   # 可选：如果需要等待调试器连接后再启动服务，取消下面注释
   # debugpy.wait_for_client()
   

3. 重启web dyno后，用Heroku的端口转发功能将本地端口映射到dyno：

   heroku ps:forward 5678
   

4. 在本地IDE中配置远程调试（以VS Code为例）：创建.vscode/launch.json，添加如下配置：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Remote Django Debug",
               "type": "python",
               "request": "attach",
               "port": 5678,
               "host": "localhost",
               "pathMappings": [
                   {
                       "localRoot": "${workspaceFolder}",
                       "remoteRoot": "/app"  # Heroku的应用根目录
                   }
               ]
           }
       ]
   }
   

5. 启动IDE的调试会话，触发线上请求后，就能在本地IDE中进行单步调试、查看变量、设置断点了。

3. 复制Heroku环境到本地 #

很多时候本地无法复现问题，是因为环境变量、数据库状态或依赖版本不一致：

• 导出环境变量：将Heroku的环境变量导出到本地：

  heroku config -s > .env
  

  然后用python-dotenv库在本地加载这些环境变量。
• 同步数据库数据：将线上数据库的数据拉到本地：

  heroku pg:pull DATABASE_URL my_local_db_name
  

  确保本地数据库和线上完全一致，更容易复现问题。
• 同步依赖版本：导出线上的依赖版本到本地：

  heroku run pip freeze > requirements.txt
  

  然后本地安装这些版本的依赖，避免版本差异导致的问题。

4. 使用错误追踪工具 #

如果问题是偶发的异常，错误追踪工具能自动捕获并提供详细上下文：

• Sentry：集成到Django后，会自动捕获所有未处理的异常，提供完整的堆栈跟踪、请求参数、用户信息甚至变量值，还能设置告警，异常发生时及时通知你。
• Heroku Error Reporting：Heroku自带的错误收集功能，能在Heroku Dashboard中查看应用的错误信息，包括堆栈跟踪和请求上下文。

5. 临时测试路由 #

可以添加一个专门的调试路由，模拟线上请求场景，不影响正常业务：

# urls.py
from django.urls import path
from django.http import HttpResponse
from myapp.views import my_problematic_view

def debug_route(request):
    # 模拟线上请求的参数、用户状态等
    request.GET = request.GET.copy()
    request.GET['critical_param'] = '线上出现问题的参数值'
    # 如果需要模拟登录用户，可以手动设置request.user
    # from django.contrib.auth.models import User
    # request.user = User.objects.get(username='test_user')
    # 调用有问题的视图函数
    response = my_problematic_view(request)
    return HttpResponse("Debug completed")

urlpatterns = [
    # 其他路由
    path('debug-route/', debug_route, name='debug-route'),
]

部署后访问这个路由，就能触发调试逻辑，不用修改正常的业务路由。

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