Django启动runserver报错UnicodeDecodeError，求解决方案

问题概述 #

首次创建的Django项目执行manage.py runserver时触发UnicodeDecodeError，核心错误为socket.getfqdn(host)无法解码字节0xcf。已确认项目路径及用户名均为英文，谷歌未找到适配解决方案。

完整错误栈 #

Performing system checks...

System check identified no issues (0 silenced).

You have 18 unapplied migration(s). Your project may not work properly until you
 apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.
August 04, 2022 - 01:06:46
Django version 4.1, using settings 'base.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.
Exception in thread django-main-thread:
Traceback (most recent call last):
  File "C:\pthn\lib\threading.py", line 932, in _bootstrap_inner
    self.run()
  File "C:\pthn\lib\threading.py", line 870, in run
    self._target(*self._args, **self._kwargs)
  File "C:\pthn\lib\site-packages\django\utils\autoreload.py", line 64, in wrapper
    fn(*args, **kwargs)
  File "C:\pthn\lib\site-packages\django\core\management\commands\runserver.py", line 158, in inner_run
    run(
  File "C:\pthn\lib\site-packages\django\core\servers\basehttp.py", line 236, in run
    httpd = httpd_cls(server_address, WSGIRequestHandler, ipv6=ipv6)
  File "C:\pthn\lib\site-packages\django\core\servers\basehttp.py", line 76, in __init__
    super().__init__(*args, **kwargs)
  File "C:\pthn\lib\socketserver.py", line 452, in __init__
    self.server_bind()
  File "C:\pthn\lib\wsgiref\simple_server.py", line 50, in server_bind
    HTTPServer.server_bind(self)
  File "C:\pthn\lib\http\server.py", line 140, in server_bind
    self.server_name = socket.getfqdn(host)
  File "C:\pthn\lib\socket.py", line 756, in getfqdn
    hostname, aliases, ipaddrs = gethostbyaddr(name)
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xcf in position 5: invalid continuation byte

本地hosts文件内容 #

# Copyright (c) 1993-2009 Microsoft Corp.
#
# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
#
# This file contains the mappings of IP addresses to host names. Each
# entry should be kept on an individual line. The IP address should
# be placed in the first column followed by the corresponding host name.
# The IP address and the host name should be separated by at least one
# space.
#
# Additionally, comments (such as these) may be inserted on individual
# lines or following the machine name denoted by a '#' symbol.
# localhost name resolution is handled within DNS itself.
#   127.0.0.1       localhost
#   ::1             localhost

错误原因 #

Python的socket.getfqdn()函数在解析主机名时，系统返回的主机名包含非UTF-8编码字符（此处为0xcf字节），导致解码失败。Windows环境下，若计算机名称含中文/非UTF-8字符，或DNS解析返回异常编码的主机名，会触发该问题。

解决方法 #

方法一：指定runserver绑定的IP #

启动服务时直接指定绑定到明确IP，跳过主机名解析：

python manage.py runserver 127.0.0.1:8000

如需允许局域网访问，可绑定到0.0.0.0：

python manage.py runserver 0.0.0.0:8000

方法二：修改计算机名称为纯英文 #

1. 右键「此电脑」→「属性」→「更改设置」→「更改」
2. 将计算机名称修改为仅含英文字母、数字的名称，重启系统后重试启动服务。

方法三：修改hosts文件强制解析 #

1. 以管理员权限打开C:\Windows\System32\drivers\etc\hosts文件
2. 添加以下内容（替换YOUR_COMPUTER_NAME为你的英文计算机名）：

127.0.0.1       YOUR_COMPUTER_NAME
::1             YOUR_COMPUTER_NAME

3. 保存文件后执行命令清除DNS缓存：

ipconfig /flushdns

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