在现代 Web 开发的架构中，前后端分离已经成为非常主流的开发模式。作为一名开发者，你可能经常会遇到这样的场景：你的前端应用（比如 React、Vue 或 Angular）运行在一个端口上（例如 localhost:8080），而你的 Django 后端 API 则运行在另一个端口上（例如 localhost:8000）。当你尝试从前端发起 API 请求时，浏览器控制台却无情地抛出了红色的错误信息。这通常是因为浏览器严格的同源策略在起作用，它阻止了一个域名的网页去请求另一个域名的资源。为了解决这个问题，我们需要启用 CORS（跨域资源共享）。
在这篇文章中，我们将深入探讨 CORS 的工作原理，并一步步引导你在 Django 项目中通过使用 django-cors-headers 这个优秀的库来配置跨域访问。我们不仅会涵盖基础的“允许所有域名”的配置，还会深入讲解如何配置白名单以应对生产环境的安全需求。让我们开始吧，掌握这项技能将极大地提升你构建全栈应用的能力。
什么是 CORS 以及为什么我们需要它？
简单来说，CORS（Cross-Origin Resource Sharing，跨域资源共享）是一种基于 HTTP 头部的机制，它允许服务器标示除了它自己以外的其他源（域、协议或端口），浏览器应该允许这些源从其加载资源。
在没有 CORS 的情况下，同源策略会阻止所谓的“跨源”请求。例如，如果你的前端应用托管在 INLINECODE3402e44a，而你的 API 托管在 INLINECODE8c9b8294，浏览器会认为这是两个不同的“源”。如果后端没有返回正确的 CORS 头部（如 Access-Control-Allow-Origin），浏览器就会拦截响应，你的前端代码也就无法获取数据。
为什么我们要关心这个？ 因为当我们将 Django 用作 REST API 的后端时，我们往往希望 API 能被各种不同的前端应用访问——无论是移动应用、单页应用（SPA）还是第三方服务。通过正确配置 CORS，我们可以明确告诉浏览器：“嘿，来自这个特定域名的请求是被允许的，请放行。”
步骤 1：安装 django-cors-headers
虽然我们可以手动编写中间件来添加 CORS 头部，但这既繁琐又容易出错。Django 社区有一个非常成熟且广泛使用的包叫做 django-cors-headers，它可以帮我们处理所有繁重的工作。
首先，我们需要通过 pip 安装这个库。打开你的终端，确保你处于你的虚拟环境中，然后运行以下命令：
# 使用 pip 安装 django-cors-headers
pip install django-cors-headers
这个库会自动处理预检请求（Preflight Requests，即 OPTIONS 请求）并添加相应的头部信息，让我们无需去关心底层 HTTP 协议的复杂细节。
步骤 2：配置 Installed Apps
安装完成后，我们需要让 Django 知道这个应用的存在。打开你的 Django 项目的 INLINECODE024591d0 文件，找到 INLINECODE637d8812 列表。我们需要在这里添加 ‘corsheaders‘。
以下是一个配置示例，展示了应该将其添加在何处：
# settings.py
INSTALLED_APPS = [
‘django.contrib.admin‘,
‘django.contrib.auth‘,
‘django.contrib.contenttypes‘,
‘django.contrib.sessions‘,
‘django.contrib.messages‘,
‘django.contrib.staticfiles‘,
# 添加这一行，注册 corsheaders 应用
‘corsheaders‘,
# 你的其他自定义应用...
# ‘rest_framework‘,
# ‘myapp‘,
]
技术提示： corsheaders 这个应用的作用是注册信号监听器，并在每次响应时检查是否需要修改响应头。安装这一步是必须的，否则中间件将无法正常工作。
步骤 3：设置 CORS 中间件
接下来，我们需要激活中间件。中间件是 Django 处理请求和响应的钩子。对于 INLINECODEb0d807d1，中间件的位置至关重要。它必须放在任何生成响应的中间件（如 INLINECODE07796a7e 或 INLINECODEed12bb81）之前，同时最好放在 INLINECODEb8dc4aca 之后。如果顺序不对，可能会导致头部无法被正确添加。
在 INLINECODEb04b6aae 中找到 INLINECODEd1b32240 列表并进行如下配置：
# settings.py
MIDDLEWARE = [
# Django 默认的安全中间件
‘django.middleware.security.SecurityMiddleware‘,
# 会话中间件
‘django.contrib.sessions.middleware.SessionMiddleware‘,
# 【关键步骤】添加 CORS 中间件
# 注意：它应该尽量靠前，以便在响应返回前拦截并添加头部
‘corsheaders.middleware.CorsMiddleware‘,
# Django 默认的通用中间件
‘django.middleware.common.CommonMiddleware‘,
# CSRF 保护中间件
‘django.middleware.csrf.CsrfViewMiddleware‘,
# 认证中间件
‘django.contrib.auth.middleware.AuthenticationMiddleware‘,
# 消息中间件
‘django.contrib.messages.middleware.MessageMiddleware‘,
# 点击劫持保护
‘django.middleware.clickjacking.XFrameOptionsMiddleware‘,
]
为什么位置这么重要？ 因为中间件是按顺序执行的。INLINECODE62a515af 需要在响应返回给浏览器之前介入，检查请求的来源并添加 INLINECODE8dd03ec3 等头部。如果它排在某些可能会修改响应或产生错误的中间件之后，CORS 检查可能会失效。
步骤 4：配置 CORS 策略（白名单与通配符）
到了这一步，我们的基础设施已经搭建完毕，现在我们需要制定具体的规则：到底允许谁来访问我们的 API？这里有两种主要的配置方式：一种是允许所有人（开发环境常用），另一种是白名单模式（生产环境推荐）。
#### 场景 A：允许所有域名（开发/测试环境）
如果你正在本地开发，或者你的 API 是完全公开的公共数据接口，你可以将 INLINECODE06be56e9 设置为 INLINECODE0d6e3319。这是最简单的配置方式，但请注意，这允许任何网站向你的 API 发送请求，这在生产环境中可能存在安全隐患。
# settings.py
# 设置为 True，允许所有域名跨域访问
CORS_ORIGIN_ALLOW_ALL = True
深度解析： 当这个变量为 INLINECODE0ed88721 时，INLINECODE15e32aaa 会忽略白名单，并强制对每个响应都添加 Access-Control-Allow-Origin: * 头部（对于非凭据请求）。这意味着任何网站的 JavaScript 代码都可以自由调用你的 API。
#### 场景 B：配置白名单（生产环境最佳实践）
在生产环境中，出于安全考虑，我们通常只允许特定的域名访问我们的 API。例如，我们可能只希望 https://www.my-frontend-app.com 能访问，而拒绝其他任何不明来源的请求。
我们需要在 settings.py 中进行如下设置：
# settings.py
# 1. 首先关闭“允许所有”
CORS_ORIGIN_ALLOW_ALL = False
# 2. 指定允许的域名列表（即白名单）
CORS_ORIGIN_WHITELIST = (
‘http://localhost:3000‘, # 常见的 React/Vue 开发服务器端口
‘http://127.0.0.1:8080‘, # 另一个本地开发地址
‘https://www.your-frontend-app.com‘, # 生产环境的前端域名
‘https://app.your-company.com‘, # 另一个被授权的应用
)
注意事项：
- 在白名单中配置域名时，请确保包含协议（http 或 https）和端口号（如果不是默认的 80 或 443）。
- 如果你需要支持子域名，例如 INLINECODE7d2a281d 和 INLINECODEc8aae2e1，你需要分别添加，或者使用正则表达式匹配（这需要使用
CORS_ORIGIN_REGEX_WHITELIST）。
让我们看一个更高级的示例，使用正则表达式来匹配多个子域名：
# settings.py
# 使用正则表达式白名单
CORS_ORIGIN_REGEX_WHITELIST = [
r‘^https://.*\.your-domain\.com$‘, # 允许 your-domain.com 下的所有 https 子域名
r‘^http://localhost.*‘, # 允许 localhost 的任何端口
]
进阶配置与实用技巧
除了基本的允许访问外，django-cors-headers 还提供了丰富的配置选项来满足复杂的业务需求。以下是几个在实际项目中非常有用的配置。
#### 1. 允许携带 Cookies 和凭证
默认情况下，浏览器为了安全，在跨域请求中不会发送 Cookie，且响应头 INLINECODE5d4091d6 会被限制为 INLINECODE9f6ed649。如果你需要前端携带 Cookie（例如使用了基于 Session 的认证），你必须显式开启 CORS_ALLOW_CREDENTIALS。
# settings.py
# 允许跨域请求携带 Cookies
CORS_ALLOW_CREDENTIALS = True
警告： 当你启用这个设置时，你不能将 INLINECODEb500833d 设置为 INLINECODE9bcf8bf8。相反，你必须在 INLINECODE5a91d080 中明确指定域名，并且服务器会返回该具体的域名，而不是 INLINECODE4c3ed0ba。这是因为 INLINECODE795f9c78 与 INLINECODEc326c791 是互斥的。
#### 2. 自定义允许的请求头
如果你的前端请求包含了一些自定义的 HTTP 头部（例如 INLINECODE107cffe1 或 INLINECODEf9ff25e3），默认情况下浏览器会阻止这些跨域头部的发送。你需要将这些头部添加到允许列表中：
# settings.py
# 允许特定的自定义请求头
CORS_ALLOW_HEADERS = [
‘accept‘,
‘accept-encoding‘,
‘authorization‘,
‘content-type‘,
‘dnt‘,
‘origin‘,
‘user-agent‘,
‘x-csrftoken‘,
‘x-requested-with‘,
‘my-custom-header‘, # 添加你的自定义头部
]
通常，默认配置已经包含了大多数标准头部，所以除非你使用了自定义头部，否则通常不需要修改这个设置。
#### 3. 允许特定的 HTTP 方法
大多数情况下，标准的 CRUD 方法（GET, POST, PUT, DELETE, PATCH）都是默认允许的。但如果你使用了不那么常见的 HTTP 方法（比如 PURGE 或 LINK），你可能需要显式声明：
# settings.py
# 允许特定的 HTTP 方法（如果默认不够用）
# 通常不需要配置，默认已经包含 ‘GET‘, ‘OPTIONS‘, ‘POST‘, ‘PUT‘, ‘PATCH‘, ‘DELETE‘
CORS_ALLOW_METHODS = [
‘DELETE‘,
‘GET‘,
‘OPTIONS‘,
‘PATCH‘,
‘POST‘,
‘PUT‘,
]
常见问题与故障排除
在实际开发中，即使配置正确，我们也可能会遇到一些棘手的问题。这里列出了一些常见的错误及其解决方案。
- 错误： "CORS policy: No ‘Access-Control-Allow-Origin‘ header is present on the requested resource."
* 原因： 请求的域名没有在白名单中，或者中间件没有生效。
* 解决： 检查 INLINECODE8f01a7cc 是否包含前端域名，并确保 INLINECODE12acd395 在 MIDDLEWARE 列表的顶部位置。
错误： "Credentials flag is true, but Access-Control-Allow-Origin is ‘‘"
* 原因： 你设置了 INLINECODE3b723de4，但同时允许了所有域名（INLINECODEde71dcdb）。
* 解决： 这是一个浏览器的硬性安全限制。你必须禁用 INLINECODEff7ccb23，并在 INLINECODEe08a0a83 中指定具体的域名。
性能与安全建议
虽然启用 CORS 很方便，但我们也要注意性能和安全性。
- 限制白名单： 在生产环境中，永远不要使用
CORS_ORIGIN_ALLOW_ALL = True，除非你的 API 确实是完全公开且无任何风险的数据。否则，应严格限制访问来源，防止 CSRF 攻击或数据泄露。 - 缓存预检请求： INLINECODE192f4101 提供了 INLINECODE7975ae58 设置。预检请求（OPTIONS）会增加网络延迟，因为浏览器在实际请求前会先发一个 OPTIONS 请求询问权限。通过设置合理的缓存时间（单位：秒），可以减少浏览器发送预检请求的频率。
# 设置预检请求缓存时间，例如 1 小时
CORS_PREFETCH_MAX_AGE = 3600
结语
通过使用 django-cors-headers，我们可以轻松、安全地在 Django 项目中实现跨域资源共享。从本地开发到生产部署，掌握这些配置将确保你的前端应用能够顺利地与后端 API 通信。我们在本文中介绍了安装、配置中间件、白名单管理以及生产环境下的安全最佳实践。
现在，你可以自信地回到你的项目中，按照这些步骤进行配置。一旦你看到前端控制台不再报错，并且能够成功获取数据，你就知道你的 CORS 配置已经完美运行了。祝你的开发过程顺利！