--- title: "Time zones" version: 3.1 locale: zh-hans source: https://docs.djangoproject.com/zh-hans/3.1/topics/i18n/timezones/ canonical: https://djangodocs.dev/zh-hans/3.1/topics/i18n/timezones/ --- # Time zones ## 概况 当启用了时区支持，Django 在数据库里以 UTC 存储日期信息，在内部使用时区感知日期对象，并且在模板和表单中转换为最终用户的时区。 如果用户居住在多个时区时，这会很方便。你要根据用户的时间来显示日期信息。 即便你的网站只在一个时区可用，在数据库中以 UTC 来存储数据是个好习惯。主要原因是夏令时。很多地方都有夏令时系统，时钟在春季向前调整，秋季向后调整。如果你以当地时间起居，那么时区转换时，每年都可能会遇到两次错误。也许这对你的博客没什么影响，但是每年两次，一次一小时多收或是少收用户的费用，这就是个问题。解决办法就是在代码里使用 UTC，并且在与最终用户交互时，使用当地时间。 时区支持模式默认是关闭的，如果要启用它，在配置文件里设置 [`USE_TZ = True`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 。时区支持模式使用 [pytz](http://pytz.sourceforge.net/) ，在安装 Django 的时候就已经安装好它了。 > **Note** > > 方便起见，在执行 [`django-admin startproject`](/zh-hans/3.1/ref/django-admin/#django-admin-startproject) 后创建默认的 `settings.py` 文件包含 [`USE_TZ = True`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 。 > **Note** > > 还有一个有关 [`USE_L10N`](/zh-hans/3.1/ref/settings/#std-setting-USE_L10N) 的设置，用来控制 Django 是否激活本地格式化。查看 [本地格式化](/zh-hans/3.1/topics/i18n/formatting/) 获取更多细节。 如果你在解决一个特定问题，从阅读 [time zone FAQ](#time-zones-faq) 开始。 ## 概念 ### Naive 日期对象与 Aware 日期对象 Python 的 [`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) 对象有一个 `tzinfo` 属性，它可以存储时区信息，表示为 [`datetime.tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) 子类的一个实例。当设置这个属性并描述了偏移量后，日期对象就是 **aware** 的，否则就是 **naive** 的。 你可以使用 [`is_aware()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.is_aware) 和 [`is_naive()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.is_naive) 来决定日期是 aware 还是 naive 的。 当关闭了时区支持，Django 会在本地时间里使用原生日期对象。这对很多用例来说足够了。在这个模式下，如果你想获取当前时间，你可以这么写： ``` import datetime now = datetime.datetime.now() ``` 当启用了时区支持 ([`USE_TZ=True`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ)) ，Django 使用 time-zone-aware 日期对象。如果你的代码创建了日期对象，她们应该也是 aware 的。在这个模式下，上面的例子变成： ``` from django.utils import timezone now = timezone.now() ``` > **Warning** > > 处理 aware 日期对象并不一直都是直观的。比如，标准日期构造函数的\`\`tzinfo\`\` 参数对于使用 DST 的时区并不可靠。使用 UTC 一般是安全的；如果你正在使用其他时区，你应该认真地看一下 [pytz](http://pytz.sourceforge.net/) 文档。 > **Note** > > Python 的 [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time) 对象还具有 `tzinfo` 属性，PostgreSQL 具有匹配 `带有时区时间` 的类型。但是，正如 PostgreSQL 所描述的，这个类型 "表现出导致问题的可用性问题"。 > > Django 只支持 naive 时间对象，如果打算保存 aware 时间对象会引发异常，因为没有关联日期的时区的时间是没有意义的。 ### Naive 日期对象的说明 当 [`USE_TZ`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 为 `True` 时，Django 仍然接受 naive 日期对象，以保持向后兼容。当数据库层收到一个日期对象，会试着让日期对象在 [default time zone](#default-current-time-zone) 里进行解释将其变为 aware 日期对象，并发出警告。 不幸的是，在 DST 转换期间，一些日期时间不存在或不明确。在这些情况下，[pytz](http://pytz.sourceforge.net/) 会引发一个异常。这就是为什么当启用时区支持的时候，需要始终创建 aware 时间对象的原因。 实际上，这种情况很罕见。Django 在模型和表单里为你提供了 aware 日期对象，并且在大部分时候，新的日期对象是通过 [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) 算法从现有的对象创建的。常在应用代码里创建的日期时间是当前时间，[`timezone.now()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.now) 会自动完成这个操作。 ### 默认时区和当前时区 **默认时区** 是通过 [`TIME_ZONE`](/zh-hans/3.1/ref/settings/#std-setting-TIME_ZONE) 定义的时区。 **当前时区** 是用来渲染的时区。 你应该使用 [`activate()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.activate) 将当前时区设置为最终用户的实际时区。 > **Note** > > 如 [`TIME_ZONE`](/zh-hans/3.1/ref/settings/#std-setting-TIME_ZONE) 文档描述，Django 设置了环境变量，因此它的进程在默认时区里运行。无论 [`USE_TZ`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 的值和当前时区如何，都会发生这种情况。 > > 当 [`USE_TZ`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 设置为 `True` 时，这样有助于保持仍然需要依赖当地时间的应用程序的后端兼容性。然而，就像前面所说（[as explained above](#naive-datetime-objects)），这样并不完全可靠，你应该始终在代码里使用 UTC 里的 aware 日期来工作。比如，使用 [`fromtimestamp()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.fromtimestamp) 并且将 `tz` 参数设置为 [`utc`](/zh-hans/3.1/ref/utils/#django.utils.timezone.utc) 。 ### 选择当前时区 当前时区相当于转换 current [locale](/zh-hans/3.1/topics/i18n/#term-locale-name) 。但是，Django 没有可用于自动确定用户时区的 `Accept-Language` HTTP header 。相反，Django 提供了时区选择函数（ [time zone selection functions](/zh-hans/3.1/ref/utils/#time-zone-selection-functions) ）。使用它们来建立对你有用的时区选择逻辑。 很多关心用户时区的站点会询问用户所在的时区，并且把这个信息保存在用户资料里。对于匿名用户，他们使用网站主要受众群体的时区或者 UTC。[pytz](http://pytz.sourceforge.net/) 提供了帮助（ [helpers](http://pytz.sourceforge.net/#helpers) ），例如每个国家时区的列表，这样你可以预先选择最有可能的选项。 这里有个在会话(session)里存储当前时区的例子。（为简单起见，它完全跳过了错误处理） 在 [`MIDDLEWARE`](/zh-hans/3.1/ref/settings/#std-setting-MIDDLEWARE): 里添加下面的中间件： ``` import pytz from django.utils import timezone class TimezoneMiddleware: def __init__(self, get_response): self.get_response = get_response def __call__(self, request): tzname = request.session.get('django_timezone') if tzname: timezone.activate(pytz.timezone(tzname)) else: timezone.deactivate() return self.get_response(request) ``` 创建一个可以设置当前时区的视图： ``` from django.shortcuts import redirect, render def set_timezone(request): if request.method == 'POST': request.session['django_timezone'] = request.POST['timezone'] return redirect('/') else: return render(request, 'template.html', {'timezones': pytz.common_timezones}) ``` 在 `template.html`  包含了一个发送 `POST` 到视图的表单： ```html+django {% load tz %} {% get_current_timezone as TIME_ZONE %}
{% csrf_token %}
``` ## 表单里的时区感知(aware)输入 当启用了时区支持，Django 会解释当前时区中以表格形式输入的日期时间，并且在 `cleaned_data` 中返回 aware 日期对象。 如果当前时区在夏令时转换（由 [pytz](http://pytz.sourceforge.net/) 提供的时区）时因日期不存在或者不明确而引发了异常，此类日期时间将被报告为无效值。 ## 模板中时区感知(aware)输出 当启用了时区支持，Django 会在模板中渲染 aware 日期时间时，将其转换为当前时区。这非常类似于本地化格式（ [format localization](/zh-hans/3.1/topics/i18n/formatting/) ）。 > **Warning** > > Django 不会转换 naive 日期对象，因为它们是不确定的，而且当开启了时区支持后，代码里绝不能生成 naive 日期。但是，你可以使用下面描述的模板过滤器那样强制转换。 转换为本地时间并不总是合适的——你或许是为计算机而不是为人类生成输出。下面的过滤器和标签，由 `tz` 模板标签库支持，允许你控制时区转换。 ### 模板标签 #### `localtime` 在包含块里开启或关闭将 aware 日期时间对象的转换为当前时区。 就模板引擎而言，该标签与 [`USE_TZ`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 具有完全相同的效果。它可以更精细地控制转换。 要模板块激活或关闭转换，使用： ```html+django {% load tz %} {% localtime on %} {{ value }} {% endlocaltime %} {% localtime off %} {{ value }} {% endlocaltime %} ``` > **Note** > > [`USE_TZ`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 的值在 `{% localtime %}` 块内被忽略。 #### `timezone` 在包含块内设置或取消当前时区。当没有设置当前时区时，会使用默认时区。 ```html+django {% load tz %} {% timezone "Europe/Paris" %} Paris time: {{ value }} {% endtimezone %} {% timezone None %} Server time: {{ value }} {% endtimezone %} ``` #### `get_current_timezone` 使用 `get_current_timezone` 标签来获取当前时区的名称： ```html+django {% get_current_timezone as TIME_ZONE %} ``` 另外，你可以激活 [`tz()`](/zh-hans/3.1/ref/templates/api/#django.template.context_processors.tz) 上下文处理器并使用 `TIME_ZONE` 上下文变量。 ### 模板过滤器 这些过滤器接受 aware 时间和 naive 时间。处于转换目的，它们假设 naive 时间在默认时区中。它们始终返回 aware 时间。 #### `localtime` 单一值强制转换为当前时区。 例如: ```html+django {% load tz %} {{ value|localtime }} ``` #### `utc` 单一值强制转换为 UTC 。 例如: ```html+django {% load tz %} {{ value|utc }} ``` #### `timezone` 单一值强制转换为任意时区。 参数必须是 [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) 子类实例或时区名。 例如: ```html+django {% load tz %} {{ value|timezone:"Europe/Paris" }} ``` ## 迁移指南 以下是迁移在 Django 支持时区之前已有项目的方法。 ### 数据库 #### PostgreSQL PostgreSQL 后端存储将日期时间存储为 `带时区的时间戳` 。事实上，这意味着它在存储时会将日期从连接的时区转换为UTC，并在检索时将UTC转换为连接的时区。 因此，如果你正在使用 PostgreSQL，你可以在 `USE_TZ = False` 和 `USE_TZ = True` 之间自由选择，数据库连接的时区将分别设置为 [`TIME_ZONE`](/zh-hans/3.1/ref/settings/#std-setting-TIME_ZONE) 或 `UTC` ，以便 Django 在所有情况下将得到正确的日期。你不需要执行任何数据转换。 #### 其他数据库 其他后端存储没有时区信息的日期。如果你的选择从 `USE_TZ = False` 变为 `USE_TZ = True` ，你必须将你的数据从本地时间转换为UTC —— 如果你的当地时间有夏令时时，则不确定。 ### 邮政编码 第一步是将 [`USE_TZ = True`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 添加到你的配置文件里。在这点上，大多数情况下都应该起作用。如果你在代码里创建 naive 日期时间对象，Django 会在必要时将它们转换为 aware 日期时间对象。 然而，这些转换有可能在夏令时转换时失败，这意味着你并有获得时区支持的所有好处。而且，在运行的时候很可能会遇到一些问题，因为它无法将 naive 日期时间和 aware 日期时间进行比较。由于 Django 现在为你提供了 aware 时间，你在比较来自模型或表单的日期与代码里创建的naive日期时间时，会遇到一些异常。 第二步是重构你在任何地方实例化的日期时间，将它们转换为 aware 日期时间。这可以逐步完成。[`django.utils.timezone`](/zh-hans/3.1/ref/utils/#module-django.utils.timezone) 为了代码兼容性而定义了一些方法：[`now()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.now), [`is_aware()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.is_aware), [`is_naive()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.is_naive), [`make_aware()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.make_aware), 和 [`make_naive()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.make_naive) 。 最后，为了帮助你定位需要升级的代码，Django 会在你试图保存 naive 日期代码到数据库的时候，引发一个告警。 ```python RuntimeWarning: DateTimeField ModelName.field_name received a naive datetime (2012-01-01 00:00:00) while time zone support is active. ``` 在开发期间，你可以通过在配置文件中添加下面的代码，使得此类警告变成异常，方便追踪： ```python import warnings warnings.filterwarnings( 'error', r"DateTimeField .* received a naive datetime", RuntimeWarning, r'django\.db\.models\.fields', ) ``` ### 辅助工具 当序列化 aware 日期时间时，会包含 UTC 偏移，如下： ```python "2011-09-01T13:20:30+03:00" ``` 对于 naive 时间，它不能这样： ```python "2011-09-01T13:20:30" ``` 对于带有 [`DateTimeField`](/zh-hans/3.1/ref/models/fields/#django.db.models.DateTimeField) 的模型，这种差异使得编写一个支持和不支持时区的辅助工具变得不可能。 使用 `USE_TZ = False` 生成辅助工具，或者 Django 1.4 版本之前，使用 "naive" 格式化。如果你的项目包含这些辅助工具，则在开始时区支持后，你将会在加载它们时，看到 [`RuntimeWarning`](https://docs.python.org/3/library/exceptions.html#RuntimeWarning) 。为了避免这些告警，你必须将辅助工具转换为 "aware" 格式。 你可以先使用 [`loaddata`](/zh-hans/3.1/ref/django-admin/#django-admin-loaddata) 然后 [`dumpdata`](/zh-hans/3.1/ref/django-admin/#django-admin-dumpdata) 重新生成辅助工具。或者，如果它们足够小，你可以对它们编辑，与将匹配到 [`TIME_ZONE`](/zh-hans/3.1/ref/settings/#std-setting-TIME_ZONE) 的 UTC 偏移量添加到每个序列化日期时间。 ## FAQ ### 安装 1. **我不需要多时区服务。我应该开启时区支持吗？** 是的。开启时区支持后，Django 会使用更准确的本地时间模型，这样使得你在夏令时转换时避免一些微秒、不可复制的错误。 开启时区支持后，会遇到一些错误，因为你使用 naive 日期时间，而 Django 期望使用 aware 日期时间。这些错误在测试的时候会显示出来。 另一方面，由于缺乏时区支持导致的bug很难预防、诊断和修复。任何涉及计划任务或日期计算的事务都有可能是潜在的bug。 基于这些原因，在新项目时要启用时区支持，除非有很好的理由，否则应该保留它。 2. **我已经开启了时区支持。我安全了吗？** 也许吧。你可以更好地避免夏令时相关错误，但你仍然可以把 naive 日期时间转换为 aware 日期时间，反之亦然。 如果你的应用连接了其他系统——比如，查询一个web服务——请确保正确指定日期时间。为了便于安全地传输时间，它们的描述应该包含 UTC 偏移量，或者它们的值应该在UTC中（或者二者都包括）。 最后，我们的日历系统包含了有趣的边缘情况。例如，你不能总是直接从给定日期中减去一年： ```python >>> import datetime >>> def one_year_before(value): # Wrong example. ... return value.replace(year=value.year - 1) >>> one_year_before(datetime.datetime(2012, 3, 1, 10, 0)) datetime.datetime(2011, 3, 1, 10, 0) >>> one_year_before(datetime.datetime(2012, 2, 29, 10, 0)) Traceback (most recent call last): ... ValueError: day is out of range for month ``` 为了正确实现这样的功能，你必须决定 2012-02-29 减去一年是 2011-02-28 还是 2011-03-01，这取决于你的业务需求。 3. **我改如何与存储本地日期时间的数据库进行交互？** 在 [`DATABASES`](/zh-hans/3.1/ref/settings/#std-setting-DATABASES) 里将:setting:TIME\_ZONE \ 选项设置为适合该数据库的时区。 当 [`USE_TZ`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 为 `True` 时，这对连接到不支持时区以及不受 Django 管理的数据库很有用。 ### 错误调试 1. **我的程序因不能比较带有偏移的 naive 日期时间与带有偏移的 aware 日期时间而崩溃——怎么回事？** 我们通过比较 naive 时间和 aware 时间来重现一下这个错误： ```python >>> import datetime >>> from django.utils import timezone >>> naive = datetime.datetime.utcnow() >>> aware = timezone.now() >>> naive == aware Traceback (most recent call last): ... TypeError: can't compare offset-naive and offset-aware datetimes ``` 如果遇到这个错误，很可能你的代码正在比较这两件事： - Django 支持的日期——比如，读取来自表单或模型字段的值。因为你开启了时区支持，所以它是 aware 的。 - 通过代码生成了日期，它是 naive 的（或者你不会读取它）。 一般来说，正确的解决办法是修改代码，用 aware 日期时间代替它。 如果你正在编写可插拔的应用独立于 [`USE_TZ`](/zh-hans/3.1/ref/settings/#std-setting-USE_TZ) 的值运行，你会发现 [`django.utils.timezone.now()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.now)  很有用。这个函数会在 `USE_TZ = False` 时将当前日期和时间作为 naive 返回，并且在 `USE_TZ = True` 时将当前日期和时间作为 aware 返回。你可以在需要时添加或减少 [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) 。 2. **我发现了很多告警：在时区支持激活后，DateTimeField 收到了 naive 日期时间((YYYY-MM-DD HH:MM:SS)) ——这样不好吗？** 当启用时区支持后，数据库层会期望仅从你的代码里收到 aware 日期。这个告警发生在数据库收到 naive 日期时间时。这表明你没有为时区支持而完成代码移植。请参考 [migration guide](#time-zones-migration-guide) 来获取此过程的提示。 在这期间，为了向后兼容，日期时间被认为处于默认时区内，通常这是你期望的。 3. `now.date()` 方法得到的结果 **为什么是昨天（或明天）？** 如果你一直在使用 naive 日期时间，你或许相信可以通过调用 [`date()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.date) 方法来将日期时间转换为日期。你也认为 [`date`](https://docs.python.org/3/library/datetime.html#datetime.date) 和 [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) 很像，除了它的准确性较差。 在 aware 日期的环境里，这些都不是正确的： ```python >>> import datetime >>> import pytz >>> paris_tz = pytz.timezone("Europe/Paris") >>> new_york_tz = pytz.timezone("America/New_York") >>> paris = paris_tz.localize(datetime.datetime(2012, 3, 3, 1, 30)) # This is the correct way to convert between time zones with pytz. >>> new_york = new_york_tz.normalize(paris.astimezone(new_york_tz)) >>> paris == new_york, paris.date() == new_york.date() (True, False) >>> paris - new_york, paris.date() - new_york.date() (datetime.timedelta(0), datetime.timedelta(1)) >>> paris datetime.datetime(2012, 3, 3, 1, 30, tzinfo=) >>> new_york datetime.datetime(2012, 3, 2, 19, 30, tzinfo=) ``` 如这个例子所示，相同 datetime 有不同的 date，这取决于它所代表的时区。但真实问题更重要。 一个 datetime 代表一个 **时间点**。它是客观存在的，不依赖任何事物。另一方面，一个 date 是一个 **日历概念** 。它是一个时间段，其范围取决于 date 所在的时区。如你所见，这两个概念在根本上是不同的，将 datetime 转换为 date 并不是确定性的操作。 这在实践中意味着什么？ 通常，你应该避免将 [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) 转换为 [`date`](https://docs.python.org/3/library/datetime.html#datetime.date) 。比如，你可以使用 [`date`](/zh-hans/3.1/ref/templates/builtins/#std-templatefilter-date) 模板过滤器来只展示 datetime 的 date 部分。这个过滤器在格式化之前将 datetime 转换为为 当前时间，确保显示正确的结果。 如果你确实需要自己进行转换，你必须首先确保 datetime 转换为合适的时区。通常，这将是当前时区： ```python >>> from django.utils import timezone >>> timezone.activate(pytz.timezone("Asia/Singapore")) # For this example, we set the time zone to Singapore, but here's how # you would obtain the current time zone in the general case. >>> current_tz = timezone.get_current_timezone() # Again, this is the correct way to convert between time zones with pytz. >>> local = current_tz.normalize(paris.astimezone(current_tz)) >>> local datetime.datetime(2012, 3, 3, 8, 30, tzinfo=) >>> local.date() datetime.date(2012, 3, 3) ``` 4. **收到“你的数据库安装时区定义了吗？”的错误** 如果你正在使用 MySQL，查看 [时区定义](/zh-hans/3.1/ref/databases/#mysql-time-zone-definitions)  部分，以获取有关加载时区定义的说明。 ### 用法 1. **有一个字符串** `"2012-02-21 10:28:45"` **并且时区是** `"Europe/Helsinki"` **。我该如何将其转换为 aware 日期时间？** 这正是 [pytz](http://pytz.sourceforge.net/) 的用途。 ``` >>> from django.utils.dateparse import parse_datetime >>> naive = parse_datetime("2012-02-21 10:28:45") >>> import pytz >>> pytz.timezone("Europe/Helsinki").localize(naive, is_dst=None) datetime.datetime(2012, 2, 21, 10, 28, 45, tzinfo=) ``` 注意 `localize` 是 [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) 的 pytz 扩展。另外，你或许想捕捉 `pytz.InvalidTimeError`。pytz 的文档包含了很多例子（ [more examples](http://pytz.sourceforge.net/#example-usage) ）。你应该在尝试操作 aware 日期时间之前看一下它。 2. **如何在当前时区里获取当地时间？** 好吧，首先要问下自己，你真的需要这么做吗？ 当与用户进行交互的时候，你只能使用当地时间，并且在模板层提供过滤器和标签，将日期时间转换为你所选择的时区。 而且，Python 知道如何去比较 aware 日期时间，并在必要时考虑 UTC 偏移量。使用 UTC 编写所有模型和视图代码里很容易（并且可能很快）。因此，在大部分情况下，由 [`django.utils.timezone.now()`](/zh-hans/3.1/ref/utils/#django.utils.timezone.now) 返回的 UTC 日期时间足够了。 但是，为了完整性，如果你真的想在当前时区里获取当地时间，你可以这么做： ```python >>> from django.utils import timezone >>> timezone.localtime(timezone.now()) datetime.datetime(2012, 3, 3, 20, 10, 53, 873365, tzinfo=) ``` 在这个例子里，当前时区是 `"Europe/Paris"` 。 3. 如何查看所有可用时区？ [pytz](http://pytz.sourceforge.net/) 提供了 [helpers](http://pytz.sourceforge.net/#helpers) ，包含当前时区列表以及所有可用时区列表 —— 其中一些时区仅具有历史意义。