Flutter Web发布后版本控制及确保用户加载最新文件的方法

一、版本控制基础 #

• 用Git管理代码版本，发布时给对应提交打版本标签，比如执行git tag v1.0.0，方便后续快速回溯或回滚版本。
• 服务器部署时可按版本号创建独立目录（如/var/www/flutter-web/v1.0.0），通过软链接指向当前生效版本目录，切换或回滚版本只需修改软链接指向，操作便捷。

二、解决main.dart.js缓存问题的核心方法 #

浏览器缓存静态资源是默认行为，要确保用户加载最新文件，可从以下几个方向入手：

1. 利用Flutter构建的哈希文件名（推荐） #

执行flutter build web时，Flutter默认会给编译后的静态文件（包括main.dart.js）添加唯一哈希后缀，比如生成main.abc123.dart.js，同时自动更新index.html里的资源引用路径。每次发布新版本，文件名都会变化，浏览器会判定为全新资源，直接加载最新内容。

若未自动生成哈希，检查pubspec.yaml无需额外配置——默认启用该功能，除非手动禁用。

2. 配置服务器HTTP缓存头 #

若无法依赖哈希文件名，可通过服务器配置缓存策略精准控制：

• 对index.html设置无缓存或短缓存（比如1分钟），确保用户每次访问都会拉取最新的index.html，进而加载其中引用的最新main.dart.js。
• 对main.dart.js可设置长缓存，但需结合版本参数（如main.dart.js?v=1.0.0），发布时手动更新参数值，让浏览器识别为新资源。

以Nginx为例，配置示例：

server {
  location / {
    root /var/www/flutter-web;
    index index.html;
    # 禁止缓存index.html
    if ($request_filename ~* index\.html$) {
      add_header Cache-Control "no-cache, no-store, must-revalidate";
      add_header Pragma "no-cache";
      add_header Expires 0;
    }
    # 带哈希的静态资源缓存1年
    location ~* \.(js|css|png|jpg)$ {
      add_header Cache-Control "public, max-age=31536000, immutable";
    }
  }
}

3. 主动实现版本更新检测 #

在Flutter Web应用内加入版本检测逻辑，主动触发刷新：

• 部署时在服务器根目录放置version.json文件，内容为当前版本号：{"version": "1.0.0"}
• 应用启动时异步请求该文件，与本地存储的版本号对比
• 若版本不一致，提示用户刷新页面，或自动执行强制刷新

示例Flutter代码：

import 'dart:convert';
import 'dart:html' as html;
import 'package:http/http.dart' as http;
import 'package:flutter/material.dart';

Future<void> checkForUpdate(BuildContext context) async {
  try {
    final response = await http.get(Uri.parse('/version.json'));
    if (response.statusCode == 200) {
      final data = json.decode(response.body);
      final latestVersion = data['version'];
      final savedVersion = html.window.localStorage['app_version'];

      if (savedVersion != latestVersion) {
        final shouldRefresh = await showDialog<bool>(
          context: context,
          builder: (context) => AlertDialog(
            title: const Text('发现新版本'),
            content: const Text('请刷新页面获取最新内容'),
            actions: [
              TextButton(
                onPressed: () => Navigator.pop(context, false),
                child: const Text('稍后'),
              ),
              TextButton(
                onPressed: () {
                  html.window.localStorage['app_version'] = latestVersion;
                  html.window.location.reload(true);
                  Navigator.pop(context, true);
                },
                child: const Text('立即刷新'),
              ),
            ],
          ),
        );
      }
    }
  } catch (e) {
    // 忽略检测失败的情况
  }
}

4. 应急强制刷新方法 #

若用户已缓存旧文件，可指导其手动按Ctrl+F5（Windows/Linux）或Cmd+Shift+R（Mac）强制浏览器跳过缓存刷新页面，但这是被动方案，优先用前面的主动策略。

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