Flask本地静态文件存在路径正确却无法访问404问题排查

问题背景 #

通过Flask的render_template方法渲染index.html文件，该文件引用CSS样式表templatemo-style.css，CSS文件内通过以下代码设置网站横幅背景图：

background-image: url(../assets/images/main-banner.jpg);

项目文件夹结构如下：

/PARENT FOLDER
   /templates
      /index.html
   /static
      /assets
         /css
            /templatemo-style.css
         /images
            /各类资源文件

运行Flask应用时终端出现404报错：

127.0.0.1 - - [02/Aug/2021 13:13:51] "GET /static/images/main-banner.jpg HTTP/1.1" 404 -

异常点为实际请求路径和代码指定路径不符，注释CSS背景图代码、排查JS代码后错误仍复现。

排查方向 #

• 检查路径规则是否匹配Flask静态资源逻辑：Flask默认将static目录下的资源挂载到/static/路由下，CSS文件的访问路径为/static/assets/css/templatemo-style.css，相对路径../assets/images/main-banner.jpg解析后应为/static/assets/images/main-banner.jpg，和报错路径不符，可排除路径写法错误问题
• 检查模板内是否有硬编码样式：排查index.html的行内样式、内部style标签是否有单独设置的背景图规则，避免优先级高于外部CSS触发异常请求
• 排查浏览器缓存问题：CSS等静态资源默认会被浏览器缓存，修改本地代码后如果未触发资源更新，浏览器会继续使用旧版CSS发起请求

最终解决方案 #

问题根源为浏览器缓存了旧的CSS文件，未加载更新后的代码。可通过两种方式解决：

1. 临时解决方案：Windows/Linux系统按Ctrl + F5，Mac系统按Command + Shift + R强制刷新页面，绕过缓存加载最新资源
2. 长期开发方案：引用静态资源时添加版本号后缀，例如CSS引用写为href="{{ url_for('static', filename='assets/css/templatemo-style.css?v=1.0') }}"，每次修改资源后更新版本号即可避免缓存问题

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