Flutter Web新增图标不可见：如何强制用户更新图标字体缓存？

问题背景 #

Flutter Web应用新增图标后，旧图标字体可能被浏览器缓存，导致新图标显示空白，手动清除缓存后可恢复正常。需要实现无需用户手动操作，让所有用户浏览器自动获取新图标字体的效果。

核心原因 #

Flutter Web构建时，Material Icons等图标字体会被打包为静态资源。浏览器会根据资源的文件名、HTTP缓存头判断是否复用本地缓存。若字体内容更新但文件名/URL未变，浏览器会继续使用旧缓存，导致新图标无法加载。

解决方案 #

1. 利用Flutter Release构建的哈希文件名特性

Flutter在flutter build web --release模式下，会为静态资源（包括字体文件）生成带唯一哈希值的文件名（例如MaterialIcons-Regular.abc123.otf）。只要重新构建并上传完整的release产物：

• 新字体文件的哈希文件名与旧文件不同，浏览器会识别为新资源，自动下载，不会复用旧缓存。
• 注意：不要添加--no-tree-shake-icons参数，该参数会禁用图标树摇，导致字体文件不更新哈希。

2. 配置HTTP缓存控制头

通过托管平台为字体文件设置合理的缓存策略：

• 结合哈希文件名：设置Cache-Control: public, max-age=31536000, immutable，让浏览器长期缓存带哈希的文件，仅当文件名（哈希）变化时才请求新资源。
• 无哈希文件名时：设置较短的缓存有效期，比如Cache-Control: public, max-age=86400（1天），或添加must-revalidate，让浏览器每次请求都验证资源是否更新。

3. 自定义字体的版本化处理（仅适用于自定义图标）

如果使用自定义图标字体，可通过修改引入路径的版本参数强制浏览器更新：

<!-- 在web/index.html中手动引入自定义字体样式时 -->
<link rel="stylesheet" href="fonts/custom-icons.css?v=2">

注：Flutter自带的Material Icons由框架自动处理引入，无法直接在index.html中修改链接。

4. 应用版本检测与强制刷新（兜底方案）

在web/index.html中添加版本检测逻辑，当应用更新时强制浏览器刷新：

// 示例：每次更新应用时修改版本号
const currentVersion = 'v2';
if (localStorage.getItem('appVersion') !== currentVersion) {
  localStorage.setItem('appVersion', currentVersion);
  window.location.reload(true); // 强制刷新，忽略缓存
}

此方法需要手动维护版本号，每次发布更新时同步修改。

验证步骤 #

1. 执行flutter build web --release生成构建产物，检查build/web/assets/fonts下的字体文件是否带有哈希后缀。
2. 上传所有构建文件到托管平台，确保覆盖旧文件。
3. 使用未清除缓存的浏览器访问应用，确认新图标正常显示。

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