如何在ISPmanager服务器上部署Flutter Web应用

1. 本地构建Flutter Web生产包 #

首先在你的Flutter项目根目录执行构建命令：
flutter build web --release
构建完成后，产物会存放在项目的build/web目录下。

注意：如果你的应用是部署在域名根路径，直接保持项目web目录下index.html里的<base href="/">配置即可；如果是部署在子路径（比如https://你的域名/app/），需要提前把base href改成对应子路径，否则部署后会出现所有静态资源404、页面白屏的问题。

2. ISPmanager面板基础配置 #

• 登录你的ISPmanager管理员/站点账号，在侧边栏找到「WWW域」（部分版本叫「网站」）选项，确认你要部署的域名已经创建为站点，记录下站点对应的根目录路径，默认路径一般为/var/www/你的域名/public_html
• 进入站点根目录，把目录里默认生成的占位index.html、测试文件全部删除，避免和你的Flutter应用冲突

3. 上传构建产物 #

两种上传方式选其一即可：

• 面板文件管理器上传：把本地build/web目录下的所有文件（包含assets、canvaskit文件夹，以及index.html、main.dart.js等所有文件）压缩为zip包，通过面板文件管理器上传到站点根目录，在线解压后确认index.html直接处于根目录下，不要出现public_html/web/index.html这类嵌套层级
• FTP上传：如果站点开启了FTP服务，用FTP工具连接服务器，同样把所有构建产物直接上传到站点根目录即可

文件权限注意：所有文件权限设置为644，文件夹权限设置为755即可，不要给777权限，避免安全问题。

4. 配置单页应用路由重写规则（必做，否则刷新子路由会404） #

Flutter Web是单页应用，所有路由都需要转发到index.html处理，根据你服务器用的web服务选对应配置：

Apache环境 #

在站点根目录新建名为.htaccess的文件，写入以下内容保存：

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

Nginx环境 #

在ISPmanager面板找到对应站点的Nginx配置编辑项，在server块的location /配置段中加入以下规则：

location / {
  try_files $uri $uri/ /index.html;
}

配置完成后，在面板的服务管理里重启对应的Apache/Nginx服务让规则生效。

5. 部署校验 #

• 直接在浏览器输入你的域名，确认应用首页可以正常加载，没有白屏问题
• 点击应用内的路由跳转到其他页面，再手动按F5刷新，确认不会出现404错误
• 打开浏览器开发者工具的控制台、网络面板，确认没有静态资源加载失败的报错

常见踩坑汇总 #

• 页面白屏：优先检查base href配置是否正确，是否漏传canvaskit、assets等静态资源文件夹
• 访问报403：检查文件权限是否正确，确认index.html直接在站点根目录下，没有嵌套文件夹
• 刷新子路由404：检查重写规则是否正确添加，web服务是否重启生效
• 部分功能加载异常：确认构建时用的是--release模式，不要用debug模式的产物部署

内容的提问来源于stack exchange，提问作者Mahmoud Haj Ali