拓冰网站优化 
【FastAPI筑基-Day9】跨域CORS彻底解决 静态文件托管前后端联调必备配置零报错专栏FastAPI 零基础后端实战系列标签FastAPI、CORS跨域、静态文件、前后端联调、static、中间件前置学习Day8 参数高级校验、Day7 三大传参方式、Day5 Pydantic 基础校验一、前言通过 Day1Day8 的学习我们已经能写 FastAPI 接口、参数校验、Pydantic 建模、各种传参方式。但是一旦前端页面访问后端接口一定会遇到两个致命问题浏览器跨域报错 CORS99% 新手卡死在这无法访问图片、JS、CSS、静态资源Day9 一次性彻底解决本文说了什么FastAPI 的跨域 CORS 配置与静态文件托管两大必备技能。实现了什么一个同时具备全局跨域中间件、静态资源目录托管、默认首页、测试接口的完整可运行项目。目的是什么学完你的 FastAPI 项目就具备线上部署能力——前后端联调无障碍、静态资源秒访问可以独立开发小型前后端分离项目。二、什么是 CORS 跨域通俗解释浏览器有一个安全策略叫同源策略只有当协议、域名、端口三个全部相同页面才能正常请求接口。只要任意一个不同就是跨域浏览器会直接拦截请求控制台报错Access to fetch at http://127.0.0.1:8000/api/hello from origin http://127.0.0.1:5500 has been blocked by CORS policy举个例子前端页面http://127.0.0.1:5500 后端接口http://127.0.0.1:8000前后端都跑在本机但端口不同5500 vs 8000→ 触发跨域 → 前端请求被浏览器拦截。FastAPI后端浏览器前端页面FastAPI后端浏览器前端页面发起 fetch 请求接口同源策略检查端口不同拦截请求控制台报 CORS 错误页面报错接口调用失败解决方案后端配置 CORS 跨域中间件明确告诉浏览器这个前端域名我信任放行。三、FastAPI 配置全局跨域企业通用万能代码依赖说明跨域中间件内置在 Starlette 中FastAPI 直接可用无需额外安装任何依赖。完整跨域配置代码fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddleware appFastAPI(titleDay9 跨域与静态文件)# 允许跨域的域名列表origins[# 本地前端常用地址http://127.0.0.1:5500,http://localhost:5500,http://127.0.0.1:8080,http://localhost:8080,]# 配置跨域中间件app.add_middleware(CORSMiddleware,allow_originsorigins,# 允许跨域的域名allow_credentialsTrue,# 允许携带 Cookieallow_methods[*],# 允许所有请求方法 GET/POST/PUT/DELETE...allow_headers[*],# 允许所有请求头)app.get(/)defindex():return{msg:跨域配置成功前端可正常访问}四个配置项含义参数含义示例allow_origins允许跨域的前端域名列表[http://127.0.0.1:5500]allow_credentials是否允许带 Cookie登录态、Session 场景必须Trueallow_methods允许的 HTTP 方法[*]表示全部放行allow_headers允许的请求头[*]表示全部放行生产环境万能写法允许所有域名内网测试、前后端分离本地调试可以直接用[*]allow_origins[*]正式上线建议写具体域名allow_origins[https://www.your-site.com]只信任自己的前端域名更安全。四、静态文件托管实现访问图片、网页、资源真实项目必须托管静态资源网站首页 HTML图片、图标、视频JS、CSS 前端资源FastAPI 通过StaticFiles实现高性能静态资源托管。第一步创建项目目录结构project/ ├─ main.py └─ static/ # 静态资源文件夹 ├─ index.html ├─ images/ │ └─ test.png └─ css/第二步挂载静态目录fromfastapi.staticfilesimportStaticFiles# 挂载静态文件夹访问路径 /staticapp.mount(/static,StaticFiles(directorystatic),namestatic)mount的含义把 URL 路径/static和本地文件夹static/一一映射。访问方式浏览器直接访问资源http://127.0.0.1:8000/static/index.html http://127.0.0.1:8000/static/images/test.png五、进阶设置网站首页默认访问静态页面光有/static路径还不够我们想要打开根路径/直接看到 HTML 首页。用FileResponse返回本地 HTML 文件fromfastapi.responsesimportFileResponseapp.get(/)asyncdefread_index():returnFileResponse(static/index.html)这样访问http://127.0.0.1:8000/就直接渲染出网站首页跟线上网站行为一致。六、Day9 最终整合完整版代码可直接上线把跨域、静态托管、首页、测试接口整合到一个文件FastAPI筑基 Day9 跨域CORS与静态文件托管 —— 配套可运行代码fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddlewarefromfastapi.responsesimportFileResponsefromfastapi.staticfilesimportStaticFiles appFastAPI(titleDay9 跨域 静态文件完整版)# 1. 跨域配置origins[http://127.0.0.1:5500,http://localhost:5500,http://127.0.0.1:8080,http://localhost:8080,]app.add_middleware(CORSMiddleware,allow_originsorigins,# 允许跨域的域名allow_credentialsTrue,# 允许携带 Cookieallow_methods[*],# 允许所有请求方法allow_headers[*],# 允许所有请求头)# 2. 挂载静态资源目录app.mount(/static,StaticFiles(directorystatic),namestatic)# 3. 默认首页app.get(/)defindex():returnFileResponse(static/index.html)# 测试接口app.get(/api/hello)defhello():return{code:200,msg:前后端联调成功}if__name____main__:importuvicorn uvicorn.run(app,host0.0.0.0,port8000)运行方式pipinstallfastapi uvicorn python3 day9.py访问http://127.0.0.1:8000/docs查看自动生成的 Swagger 接口文档。七、运行验证全链路实测本机验证时 8000 端口被其他服务占用我改用端口8008启动配置方式完全一致所有结果均为实测输出。1. Swagger 接口文档启动后自动生成接口文档包含/首页和/api/hello测试接口2. 静态首页渲染打开根路径/FileResponse直接渲染出静态 HTML 首页3. 静态图片访问浏览器直接访问/static/images/下的图片托管成功4. 前后端跨域联调重点验证前端页面跑在 5500 端口后端接口跑在 8008 端口端口不同。点击按钮跨域请求后端接口请求成功并拿到 JSON 数据这是本次配置的核心价值——没有 CORS 中间件这一步 100% 报错。5. 命令行实测curl 验证 CORS 响应头 合法 Origin5500发出跨域预检请求 请求头Origin: http://127.0.0.1:5500 响应头access-control-allow-origin: http://127.0.0.1:5500 access-control-allow-credentials: true access-control-allow-methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT 未授权 Originevil.com发出跨域预检请求 响应头access-control-allow-methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT 注意没有 access-control-allow-origin 响应头 → 浏览器拦截白名单内的域名拿到了access-control-allow-origin响应头浏览器放行白名单外的域名拿不到该头浏览器照常拦截。CORS 配置生效。6. 服务端访问日志INFO: Uvicorn running on http://127.0.0.1:8008 (Press CTRLC to quit) INFO: 127.0.0.1:50332 - GET / HTTP/1.1 200 OK INFO: 127.0.0.1:50338 - GET /static/images/test.png HTTP/1.1 200 OK INFO: 127.0.0.1:50350 - GET /api/hello HTTP/1.1 200 OK首页、静态图片、接口全部 200全链路打通。八、Day9 核心知识点总结知识点说明CORS 跨域浏览器同源策略限制后端配置中间件解决allow_origins配置允许访问的前端域名上线写具体域名更安全allow_credentials允许携带 Cookie登录态场景必须TrueStaticFilesFastAPI 静态资源托管方案app.mount指定 URL 路径与本地文件夹映射FileResponse返回本地 HTML 文件实现网站首页九、实际开发价值学到这里你的项目已经具备完整接口能力工业级参数校验前后端跨域打通静态网站托管能力完全可以独立开发小型前后端分离项目至此FastAPI 核心基础全部学完——从异步入门、日志封装、命令行参数、高并发爬虫、Pydantic 校验、接口编写、传参方式、高级校验到今天的跨域与静态托管整个闭环齐了。十、下期预告Day10FastAPI 异常捕获 全局统一响应结果统一返回格式、统一错误码、全局异常拦截企业项目标准化收尾 FastAPI筑基_Day9_跨域CORS与静态文件托管
【FastAPI筑基-Day9】跨域CORS彻底解决 静态文件托管前后端联调必备配置零报错专栏FastAPI 零基础后端实战系列标签FastAPI、CORS跨域、静态文件、前后端联调、static、中间件前置学习Day8 参数高级校验、Day7 三大传参方式、Day5 Pydantic 基础校验一、前言通过 Day1Day8 的学习我们已经能写 FastAPI 接口、参数校验、Pydantic 建模、各种传参方式。但是一旦前端页面访问后端接口一定会遇到两个致命问题浏览器跨域报错 CORS99% 新手卡死在这无法访问图片、JS、CSS、静态资源Day9 一次性彻底解决本文说了什么FastAPI 的跨域 CORS 配置与静态文件托管两大必备技能。实现了什么一个同时具备全局跨域中间件、静态资源目录托管、默认首页、测试接口的完整可运行项目。目的是什么学完你的 FastAPI 项目就具备线上部署能力——前后端联调无障碍、静态资源秒访问可以独立开发小型前后端分离项目。二、什么是 CORS 跨域通俗解释浏览器有一个安全策略叫同源策略只有当协议、域名、端口三个全部相同页面才能正常请求接口。只要任意一个不同就是跨域浏览器会直接拦截请求控制台报错Access to fetch at http://127.0.0.1:8000/api/hello from origin http://127.0.0.1:5500 has been blocked by CORS policy举个例子前端页面http://127.0.0.1:5500 后端接口http://127.0.0.1:8000前后端都跑在本机但端口不同5500 vs 8000→ 触发跨域 → 前端请求被浏览器拦截。FastAPI后端浏览器前端页面FastAPI后端浏览器前端页面发起 fetch 请求接口同源策略检查端口不同拦截请求控制台报 CORS 错误页面报错接口调用失败解决方案后端配置 CORS 跨域中间件明确告诉浏览器这个前端域名我信任放行。三、FastAPI 配置全局跨域企业通用万能代码依赖说明跨域中间件内置在 Starlette 中FastAPI 直接可用无需额外安装任何依赖。完整跨域配置代码fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddleware appFastAPI(titleDay9 跨域与静态文件)# 允许跨域的域名列表origins[# 本地前端常用地址http://127.0.0.1:5500,http://localhost:5500,http://127.0.0.1:8080,http://localhost:8080,]# 配置跨域中间件app.add_middleware(CORSMiddleware,allow_originsorigins,# 允许跨域的域名allow_credentialsTrue,# 允许携带 Cookieallow_methods[*],# 允许所有请求方法 GET/POST/PUT/DELETE...allow_headers[*],# 允许所有请求头)app.get(/)defindex():return{msg:跨域配置成功前端可正常访问}四个配置项含义参数含义示例allow_origins允许跨域的前端域名列表[http://127.0.0.1:5500]allow_credentials是否允许带 Cookie登录态、Session 场景必须Trueallow_methods允许的 HTTP 方法[*]表示全部放行allow_headers允许的请求头[*]表示全部放行生产环境万能写法允许所有域名内网测试、前后端分离本地调试可以直接用[*]allow_origins[*]正式上线建议写具体域名allow_origins[https://www.your-site.com]只信任自己的前端域名更安全。四、静态文件托管实现访问图片、网页、资源真实项目必须托管静态资源网站首页 HTML图片、图标、视频JS、CSS 前端资源FastAPI 通过StaticFiles实现高性能静态资源托管。第一步创建项目目录结构project/ ├─ main.py └─ static/ # 静态资源文件夹 ├─ index.html ├─ images/ │ └─ test.png └─ css/第二步挂载静态目录fromfastapi.staticfilesimportStaticFiles# 挂载静态文件夹访问路径 /staticapp.mount(/static,StaticFiles(directorystatic),namestatic)mount的含义把 URL 路径/static和本地文件夹static/一一映射。访问方式浏览器直接访问资源http://127.0.0.1:8000/static/index.html http://127.0.0.1:8000/static/images/test.png五、进阶设置网站首页默认访问静态页面光有/static路径还不够我们想要打开根路径/直接看到 HTML 首页。用FileResponse返回本地 HTML 文件fromfastapi.responsesimportFileResponseapp.get(/)asyncdefread_index():returnFileResponse(static/index.html)这样访问http://127.0.0.1:8000/就直接渲染出网站首页跟线上网站行为一致。六、Day9 最终整合完整版代码可直接上线把跨域、静态托管、首页、测试接口整合到一个文件FastAPI筑基 Day9 跨域CORS与静态文件托管 —— 配套可运行代码fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddlewarefromfastapi.responsesimportFileResponsefromfastapi.staticfilesimportStaticFiles appFastAPI(titleDay9 跨域 静态文件完整版)# 1. 跨域配置origins[http://127.0.0.1:5500,http://localhost:5500,http://127.0.0.1:8080,http://localhost:8080,]app.add_middleware(CORSMiddleware,allow_originsorigins,# 允许跨域的域名allow_credentialsTrue,# 允许携带 Cookieallow_methods[*],# 允许所有请求方法allow_headers[*],# 允许所有请求头)# 2. 挂载静态资源目录app.mount(/static,StaticFiles(directorystatic),namestatic)# 3. 默认首页app.get(/)defindex():returnFileResponse(static/index.html)# 测试接口app.get(/api/hello)defhello():return{code:200,msg:前后端联调成功}if__name____main__:importuvicorn uvicorn.run(app,host0.0.0.0,port8000)运行方式pipinstallfastapi uvicorn python3 day9.py访问http://127.0.0.1:8000/docs查看自动生成的 Swagger 接口文档。七、运行验证全链路实测本机验证时 8000 端口被其他服务占用我改用端口8008启动配置方式完全一致所有结果均为实测输出。1. Swagger 接口文档启动后自动生成接口文档包含/首页和/api/hello测试接口2. 静态首页渲染打开根路径/FileResponse直接渲染出静态 HTML 首页3. 静态图片访问浏览器直接访问/static/images/下的图片托管成功4. 前后端跨域联调重点验证前端页面跑在 5500 端口后端接口跑在 8008 端口端口不同。点击按钮跨域请求后端接口请求成功并拿到 JSON 数据这是本次配置的核心价值——没有 CORS 中间件这一步 100% 报错。5. 命令行实测curl 验证 CORS 响应头 合法 Origin5500发出跨域预检请求 请求头Origin: http://127.0.0.1:5500 响应头access-control-allow-origin: http://127.0.0.1:5500 access-control-allow-credentials: true access-control-allow-methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT 未授权 Originevil.com发出跨域预检请求 响应头access-control-allow-methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT 注意没有 access-control-allow-origin 响应头 → 浏览器拦截白名单内的域名拿到了access-control-allow-origin响应头浏览器放行白名单外的域名拿不到该头浏览器照常拦截。CORS 配置生效。6. 服务端访问日志INFO: Uvicorn running on http://127.0.0.1:8008 (Press CTRLC to quit) INFO: 127.0.0.1:50332 - GET / HTTP/1.1 200 OK INFO: 127.0.0.1:50338 - GET /static/images/test.png HTTP/1.1 200 OK INFO: 127.0.0.1:50350 - GET /api/hello HTTP/1.1 200 OK首页、静态图片、接口全部 200全链路打通。八、Day9 核心知识点总结知识点说明CORS 跨域浏览器同源策略限制后端配置中间件解决allow_origins配置允许访问的前端域名上线写具体域名更安全allow_credentials允许携带 Cookie登录态场景必须TrueStaticFilesFastAPI 静态资源托管方案app.mount指定 URL 路径与本地文件夹映射FileResponse返回本地 HTML 文件实现网站首页九、实际开发价值学到这里你的项目已经具备完整接口能力工业级参数校验前后端跨域打通静态网站托管能力完全可以独立开发小型前后端分离项目至此FastAPI 核心基础全部学完——从异步入门、日志封装、命令行参数、高并发爬虫、Pydantic 校验、接口编写、传参方式、高级校验到今天的跨域与静态托管整个闭环齐了。十、下期预告Day10FastAPI 异常捕获 全局统一响应结果统一返回格式、统一错误码、全局异常拦截企业项目标准化收尾