django-user_agents 完整安装与配置教程：从 pip 到 Memcached 缓存的清单式指南

django-user_agents 完整安装与配置教程：从 pip 到 Memcached 缓存的清单式指南

【免费下载链接】django-user_agentsA django package that allows easy identification of visitor's browser, OS and device information, including whether the visitor uses a mobile phone, tablet or a touch capable device.项目地址: https://gitcode.com/gh_mirrors/dj/django-user_agents

django-user_agents 是一个专门用于识别访客浏览器、操作系统与设备信息的 Django 第三方包，它能在后台解析 HTTP 请求中的 User-Agent，帮你判断访客使用的是手机、平板、PC 还是支持触摸的设备。本文提供一份从 pip 安装到 Memcached 缓存加速的 django-user_agents 完整安装与配置教程，全程清单式讲解，即使你是 Django 新手，也能按步骤轻松落地。

django-user_agents 是什么？为什么需要它？🧐

在做移动端适配、统计上报或权限控制时，我们常常需要知道"来访者用的什么设备"。手写正则解析 User-Agent 既繁琐又容易出错，而 django-user_agents 把这件事封装成了开箱即用的工具：

• 识别浏览器（family、版本号）
• 识别操作系统（如 iOS、Android、Windows）
• 识别设备类型（手机、平板、PC、触摸设备）
• 识别爬虫/机器人（bot）

它底层依赖user-agents、ua-parser等成熟解析库，你只需要调用几个简单的属性即可。核心逻辑集中在两个文件里：解析入口在 django_user_agents/utils.py，中间件实现则在 django_user_agents/middleware.py。

安装前的准备工作：环境与依赖清单 ✅

开始安装前，先确认你的环境满足以下条件：

本包本身依赖django与user-agents，而user-agents又依赖ua-parser和pyyaml，建议一起安装，避免遗漏。

最快的 pip 安装步骤（4 条命令搞定）⚡

这是最推荐的安装方式，两步共 4 条命令即可完成：

pip install pyyaml ua-parser user-agents pip install django-user-agents

安装完成后，可以用下面的命令验证是否成功：

pip show django-user-agents

如果你希望直接查看源码或参与二次开发，也可以克隆仓库再安装：

git clone https://gitcode.com/gh_mirrors/dj/django-user_agents cd django-user_agents pip install -e .

settings.py 配置方法：注册应用与指定缓存 🛠️

安装只是第一步，接下来需要把django_user_agents注册进INSTALLED_APPS，并告诉它使用哪个缓存：

INSTALLED_APPS = ( # 其他应用... 'django_user_agents', ) # 指定缓存别名；设为 None 可关闭缓存 USER_AGENTS_CACHE = 'default'

这里有个小细节：USER_AGENTS_CACHE默认使用default缓存别名。项目测试配置可以参考 django_user_agents/tests/settings.py，里面同时展示了旧版MIDDLEWARE_CLASSES与新版MIDDLEWARE两种写法。

中间件配置：让 request 自带 user_agent 属性 🔌

在MIDDLEWARE（Django 1.10+）中加入UserAgentMiddleware：

MIDDLEWARE = [ # 其他中间件... 'django_user_agents.middleware.UserAgentMiddleware', ]

如果你的 Django 版本较老（低于 1.10），请使用MIDDLEWARE_CLASSES列表，路径写法相同。启用后，每个请求都会自动获得request.user_agent属性（采用懒加载实现，未使用时不会增加解析开销）。

三种使用方式：视图、模板与过滤器 📖

方式一：在视图中读取设备信息

def my_view(request): # 假设访客使用的是 iPhone request.user_agent.is_mobile # True request.user_agent.is_tablet # False request.user_agent.is_touch_capable # True request.user_agent.is_pc # False request.user_agent.is_bot # False # 浏览器信息 request.user_agent.browser.family # 'Mobile Safari' request.user_agent.browser.version_string # '5.1' # 操作系统信息 request.user_agent.os.family # 'iOS' request.user_agent.os.version_string # '5.1' # 设备信息 request.user_agent.device.family # 'iPhone'

如果你不想依赖中间件，也可以直接从工具函数拿结果：django_user_agents/utils.py 中导出的get_user_agent(request)同样返回一个UserAgent实例。

方式二：在模板中直接判断

启用django.core.context_processors.request后，模板里就能直接使用request.user_agent：

{% if request.user_agent.is_mobile %} <!-- 移动端专属内容 --> {% endif %} {% if request.user_agent.is_touch_capable %} <!-- 触摸屏优化 --> {% endif %}

方式三：使用模板过滤器（最简洁）

先{% load user_agents %}，然后就能用 5 个现成过滤器，它们的实现都定义在 django_user_agents/templatetags/user_agents.py：

{% load user_agents %} {% if request|is_mobile %} 移动端内容 {% endif %} {% if request|is_tablet %} 平板内容 {% endif %} {% if request|is_pc %} PC 内容 {% endif %} {% if request|is_touch_capable %} 触摸设备内容 {% endif %} {% if request|is_bot %} 爬虫友好内容 {% endif %}

五种过滤器对应关系如下：

Memcached 缓存配置：让解析速度起飞 🚀

User-Agent 解析依赖正则规则匹配，本身有一定开销。django-user_agents 内置了缓存机制：先用 UA 字符串的 MD5 作为缓存键查询，命中则直接返回结果，未命中才真正解析。这一逻辑就在get_user_agent()与get_cache_key()中（见 django_user_agents/utils.py），并且它对超过 250 字符的超长 UA 也做了 MD5 处理，不用担心缓存键超限。

给settings.py加上 Memcached 后端即可生效：

CACHES = { 'default': { 'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', 'LOCATION': '127.0.0.1:11211', } }

小提示：如果你用的是较新的 Django 版本，推荐改用django.core.cache.backends.memcached.PyMemcacheCache后端；不想用缓存时，把USER_AGENTS_CACHE设为None即可关闭。

常见问题排查清单 🔍

• 报错ImportError？多半是pyyaml、ua-parser没装齐，按上文 4 条命令重新安装。
• 模板里request.user_agent取不到？检查是否启用了django.core.context_processors.request。
• 缓存一直不生效？确认USER_AGENTS_CACHE指向的别名真实存在，且 Memcached 服务已启动。
• 空 UA 请求导致异常？0.1.1 版本已修复空HTTP_USER_AGENT时的KeyError，请升级到最新版本。
• 老项目无法升级？注意 0.4.0 支持 Django 2.0~2.2，Python 3 兼容由 0.3.0 引入，升级前先看版本记录。

总结 📝

按这份清单走完，你的 Django 项目就拥有了完整的访客设备识别能力：pip 安装依赖、注册应用、挂载中间件、三种方式读取设备信息，最后用 Memcached 缓存把解析开销降到最低。无论是做移动端跳转、响应式适配还是爬虫防护，django-user_agents 都能让你少写大量正则代码，把精力放在真正的业务上。

【免费下载链接】django-user_agentsA django package that allows easy identification of visitor's browser, OS and device information, including whether the visitor uses a mobile phone, tablet or a touch capable device.项目地址: https://gitcode.com/gh_mirrors/dj/django-user_agents