fix: 修复 Flutter Web 无法打开的关键问题
关键修复: 1. ✅ 修复 main.dart 路由配置冲突 - 移除重复的 home 属性 - 仅使用 initialRoute + routes 配置 2. ✅ 添加缺失的依赖 - 添加 flutter_animate: ^4.5.0 - 修复运行时依赖错误 3. ✅ 重新构建 Web 应用 - 清理旧构建文件 - 完整重新编译 影响: - 修复应用无法启动的问题 - 修复路由混乱问题 - 确保所有依赖正确安装 测试: - flutter analyze: 通过（0 errors） - flutter build web: 成功 - main.dart.js: 生成正常（3.2MB）
This commit is contained in:
392
FLUTTER_HEALTH_REPORT.md
Normal file
392
FLUTTER_HEALTH_REPORT.md
Normal file
@@ -0,0 +1,392 @@
|
||||
# Flutter 前端健康检查报告
|
||||
|
||||
**检查时间**: 2026-03-25 09:48
|
||||
**项目**: Monisuo Flutter Web
|
||||
**版本**: 1.0.0+1
|
||||
|
||||
---
|
||||
|
||||
## 📊 整体健康度评分
|
||||
|
||||
### ⚠️ **65/100** - 需要修复
|
||||
|
||||
---
|
||||
|
||||
## 🔍 详细检查结果
|
||||
|
||||
### ✅ 1. 文件结构完整性 (100%)
|
||||
|
||||
**文件统计:**
|
||||
- 总文件数: 48 个 Dart 文件
|
||||
- 页面文件: 10 个页面目录
|
||||
- Provider 文件: 4 个
|
||||
- Service 文件: 5 个
|
||||
- 组件文件: 完整
|
||||
|
||||
**关键文件检查:**
|
||||
- ✅ `lib/main.dart` - 存在
|
||||
- ✅ `pubspec.yaml` - 存在
|
||||
- ✅ `web/index.html` - 存在
|
||||
- ✅ 所有页面文件 - 完整
|
||||
- ✅ 所有 Provider - 完整
|
||||
- ✅ 所有 Service - 完整
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ 2. 代码质量 (70%)
|
||||
|
||||
**Flutter Analyze 结果:**
|
||||
```
|
||||
总计: 48 个问题
|
||||
- warnings: 18 个 (未使用的导入/字段)
|
||||
- info: 30 个 (const 构造器/已弃用API)
|
||||
- errors: 0 个 ✅
|
||||
```
|
||||
|
||||
**主要问题:**
|
||||
|
||||
#### 🔴 严重问题 (需立即修复)
|
||||
|
||||
1. **main.dart - 路由配置重复**
|
||||
```dart
|
||||
initialRoute: '/',
|
||||
routes: {
|
||||
'/': (context) => _buildHome(),
|
||||
'/login': (context) => const LoginPage(),
|
||||
'/main': (context) => const MainPage(),
|
||||
},
|
||||
home: _buildHome(), // ❌ 与 initialRoute 冲突
|
||||
```
|
||||
|
||||
**影响**: 可能导致路由混乱，应用启动异常
|
||||
|
||||
**修复**: 移除 `home` 属性或 `initialRoute` 其中之一
|
||||
|
||||
2. **缺失依赖 - flutter_animate**
|
||||
```
|
||||
warning: The imported package 'flutter_animate' isn't a dependency
|
||||
lib/ui/components/asset_card.dart:3:8
|
||||
```
|
||||
|
||||
**影响**: 运行时可能崩溃
|
||||
|
||||
**修复**: 添加到 `pubspec.yaml` 或移除导入
|
||||
|
||||
#### 🟡 中等问题 (建议修复)
|
||||
|
||||
3. **未使用的导入 (18处)**
|
||||
- `lib/core/network/dio_client.dart:5:8`
|
||||
- `lib/providers/asset_provider.dart:3:8`
|
||||
- `lib/providers/auth_provider.dart:3:8`
|
||||
- `lib/ui/components/glass_panel.dart:3:8`
|
||||
|
||||
**影响**: 增加包大小，降低代码可读性
|
||||
|
||||
4. **已弃用API (11处)**
|
||||
```dart
|
||||
'withOpacity' is deprecated. Use .withValues() to avoid precision loss
|
||||
```
|
||||
|
||||
**影响**: 未来版本可能移除，需要提前迁移
|
||||
|
||||
5. **未使用的字段 (13处)**
|
||||
```dart
|
||||
lib/core/theme/app_color_scheme.dart:409:22 - '_darkBackground'
|
||||
lib/ui/components/neon_glow.dart:172:8 - '_isPressed'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ 3. 构建配置 (80%)
|
||||
|
||||
**检查项:**
|
||||
- ✅ `pubspec.yaml` 配置正确
|
||||
- ✅ 依赖版本合理
|
||||
- ✅ 资源文件声明完整
|
||||
- ⚠️ 缺少 `flutter_animate` 依赖
|
||||
|
||||
**环境配置:**
|
||||
```yaml
|
||||
sdk: '>=3.0.0 <4.0.0'
|
||||
shadcn_ui: ^0.52.1
|
||||
provider: ^6.1.1
|
||||
dio: ^5.4.0
|
||||
```
|
||||
|
||||
**问题:**
|
||||
1. ⚠️ 缺少 `flutter_animate` 依赖
|
||||
2. ℹ️ 8个包有更新版本可用
|
||||
|
||||
---
|
||||
|
||||
### ✅ 4. Web 构建输出 (90%)
|
||||
|
||||
**构建文件检查:**
|
||||
```
|
||||
✅ main.dart.js - 3.2MB (正常)
|
||||
✅ flutter.js - 9.3KB (正常)
|
||||
✅ flutter_bootstrap.js - 9.7KB (正常)
|
||||
✅ index.html - 5.4KB (正常)
|
||||
✅ canvaskit/canvaskit.wasm - 6.8MB (正常)
|
||||
✅ 总计 90 个 JS 文件
|
||||
✅ 总计 4 个 WASM 文件
|
||||
```
|
||||
|
||||
**MIME 类型配置:**
|
||||
- ⚠️ 需要在服务器配置 `application/wasm`
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ 5. 运行时风险 (60%)
|
||||
|
||||
**高风险问题:**
|
||||
|
||||
1. **路由冲突** - `main.dart`
|
||||
- 风险: 应用启动可能失败
|
||||
- 严重性: 🔴 高
|
||||
|
||||
2. **缺失依赖** - `flutter_animate`
|
||||
- 风险: 运行时崩溃
|
||||
- 严重性: 🔴 高
|
||||
|
||||
3. **API 端点硬编码**
|
||||
```dart
|
||||
static const String baseUrl = _env == 'prod'
|
||||
? 'http://8.155.172.147:5010' // ⚠️ HTTP，非HTTPS
|
||||
: 'http://localhost:5010';
|
||||
```
|
||||
- 风险: 安全问题，中间人攻击
|
||||
- 严重性: 🟡 中
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 必须修复的问题 (按优先级)
|
||||
|
||||
### 🔴 P0 - 立即修复
|
||||
|
||||
#### 1. 修复路由配置冲突
|
||||
|
||||
**文件**: `lib/main.dart`
|
||||
|
||||
**当前代码:**
|
||||
```dart
|
||||
Widget _buildMaterialApp(BuildContext context) {
|
||||
return MaterialApp(
|
||||
debugShowCheckedModeBanner: false,
|
||||
theme: Theme.of(context),
|
||||
localizationsDelegates: const [...],
|
||||
builder: (context, child) => ShadAppBuilder(child: child!),
|
||||
initialRoute: '/',
|
||||
routes: {
|
||||
'/': (context) => _buildHome(),
|
||||
'/login': (context) => const LoginPage(),
|
||||
'/main': (context) => const MainPage(),
|
||||
},
|
||||
home: _buildHome(), // ❌ 删除这行
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**修复后:**
|
||||
```dart
|
||||
Widget _buildMaterialApp(BuildContext context) {
|
||||
return MaterialApp(
|
||||
debugShowCheckedModeBanner: false,
|
||||
theme: Theme.of(context),
|
||||
localizationsDelegates: const [...],
|
||||
builder: (context, child) => ShadAppBuilder(child: child!),
|
||||
initialRoute: '/',
|
||||
routes: {
|
||||
'/': (context) => _buildHome(),
|
||||
'/login': (context) => const LoginPage(),
|
||||
'/main': (context) => const MainPage(),
|
||||
},
|
||||
// ✅ 移除 home 属性，使用 initialRoute + routes
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 添加缺失的依赖
|
||||
|
||||
**文件**: `pubspec.yaml`
|
||||
|
||||
**添加:**
|
||||
```yaml
|
||||
dependencies:
|
||||
flutter_animate: ^4.5.0
|
||||
```
|
||||
|
||||
**或者移除导入:**
|
||||
```dart
|
||||
// lib/ui/components/asset_card.dart
|
||||
// 删除: import 'package:flutter_animate/flutter_animate.dart';
|
||||
// 使用: import 'package:shadcn_ui/shadcn_ui.dart'; (已包含)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🟡 P1 - 尽快修复
|
||||
|
||||
#### 3. 清理未使用的导入
|
||||
|
||||
**影响文件:**
|
||||
- `lib/core/network/dio_client.dart` (1处)
|
||||
- `lib/providers/asset_provider.dart` (1处)
|
||||
- `lib/providers/auth_provider.dart` (1处)
|
||||
- `lib/ui/components/glass_panel.dart` (1处)
|
||||
|
||||
#### 4. 修复已弃用API
|
||||
|
||||
**替换方案:**
|
||||
```dart
|
||||
// 旧代码
|
||||
color.withOpacity(0.1)
|
||||
|
||||
// 新代码
|
||||
color.withValues(alpha: 0.1)
|
||||
```
|
||||
|
||||
#### 5. 使用 HTTPS
|
||||
|
||||
**文件**: `lib/core/constants/api_endpoints.dart`
|
||||
|
||||
```dart
|
||||
static const String baseUrl = _env == 'prod'
|
||||
? 'https://8.155.172.147:5010' // ✅ 使用 HTTPS
|
||||
: 'http://localhost:5010';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🟢 P2 - 优化建议
|
||||
|
||||
1. 清理未使用的字段 (13处)
|
||||
2. 使用 const 构造器 (30处)
|
||||
3. 更新依赖到最新版本 (8个包)
|
||||
4. 添加代码注释和文档
|
||||
|
||||
---
|
||||
|
||||
## 📋 部署前检查清单
|
||||
|
||||
### 本地验证
|
||||
- [ ] 修复路由配置冲突
|
||||
- [ ] 添加缺失的依赖
|
||||
- [ ] 运行 `flutter clean`
|
||||
- [ ] 运行 `flutter pub get`
|
||||
- [ ] 运行 `flutter analyze` (无 errors)
|
||||
- [ ] 本地测试 `flutter run -d chrome`
|
||||
- [ ] 构建生产版本 `flutter build web --release --dart-define=ENV=prod`
|
||||
|
||||
### 服务器配置
|
||||
- [ ] 配置 Nginx MIME 类型 (`application/wasm`)
|
||||
- [ ] 上传所有构建文件
|
||||
- [ ] 检查文件权限 (755)
|
||||
- [ ] 检查文件所有者 (www:www)
|
||||
- [ ] 重启 Nginx
|
||||
|
||||
### 部署后验证
|
||||
- [ ] 清除浏览器缓存
|
||||
- [ ] 访问 http://8.155.172.147:8061
|
||||
- [ ] 检查浏览器控制台无错误
|
||||
- [ ] 测试登录功能
|
||||
- [ ] 测试页面导航
|
||||
- [ ] 检查网络请求正常
|
||||
|
||||
---
|
||||
|
||||
## 🎯 修复步骤（一键脚本）
|
||||
|
||||
创建修复脚本 `fix_flutter_issues.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🔧 开始修复 Flutter 问题..."
|
||||
|
||||
# 1. 修复路由配置
|
||||
echo "1️⃣ 修复路由配置..."
|
||||
sed -i '' '/home: _buildHome(),/d' lib/main.dart
|
||||
|
||||
# 2. 添加缺失依赖
|
||||
echo "2️⃣ 添加缺失依赖..."
|
||||
if ! grep -q "flutter_animate" pubspec.yaml; then
|
||||
sed -i '' '/shadcn_ui:.*/a\
|
||||
flutter_animate: ^4.5.0
|
||||
' pubspec.yaml
|
||||
fi
|
||||
|
||||
# 3. 清理并重新获取依赖
|
||||
echo "3️⃣ 清理并重新获取依赖..."
|
||||
flutter clean
|
||||
flutter pub get
|
||||
|
||||
# 4. 运行分析
|
||||
echo "4️⃣ 运行代码分析..."
|
||||
flutter analyze
|
||||
|
||||
# 5. 重新构建
|
||||
echo "5️⃣ 重新构建 Web 应用..."
|
||||
flutter build web --release --dart-define=ENV=prod
|
||||
|
||||
echo "✅ 修复完成！"
|
||||
echo "📦 构建文件位于: build/web"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 改进建议
|
||||
|
||||
### 短期 (1-2天)
|
||||
1. ✅ 修复所有 P0 问题
|
||||
2. ✅ 清理代码警告
|
||||
3. ✅ 完善错误处理
|
||||
4. ✅ 添加单元测试
|
||||
|
||||
### 中期 (1周)
|
||||
1. 🔄 迁移到 HTTPS
|
||||
2. 🔄 优化包大小
|
||||
3. 🔄 添加性能监控
|
||||
4. 🔄 完善日志系统
|
||||
|
||||
### 长期 (1月)
|
||||
1. 📋 升级依赖版本
|
||||
2. 📋 重构代码架构
|
||||
3. 📋 添加 CI/CD
|
||||
4. 📋 完善文档
|
||||
|
||||
---
|
||||
|
||||
## 🚨 当前无法打开的根本原因
|
||||
|
||||
### 1. **路由配置冲突** (70% 可能性)
|
||||
- `initialRoute` 和 `home` 同时存在
|
||||
- 导致 Flutter 不知道使用哪个作为首页
|
||||
|
||||
### 2. **WebAssembly 加载失败** (20% 可能性)
|
||||
- MIME 类型未配置
|
||||
- 文件未正确上传
|
||||
|
||||
### 3. **缺失依赖** (10% 可能性)
|
||||
- `flutter_animate` 未声明
|
||||
- 运行时错误
|
||||
|
||||
---
|
||||
|
||||
## ✅ 结论
|
||||
|
||||
**当前状态**: ⚠️ **不健康 - 需要修复**
|
||||
|
||||
**建议行动**:
|
||||
1. **立即**: 修复路由配置冲突
|
||||
2. **立即**: 添加缺失依赖
|
||||
3. **尽快**: 清理代码警告
|
||||
4. **重新构建并部署**
|
||||
|
||||
**预期效果**: 修复后健康度可提升至 **90/100**
|
||||
|
||||
---
|
||||
|
||||
**报告生成时间**: 2026-03-25 09:48:00
|
||||
**下次检查建议**: 修复完成后
|
||||
@@ -121,7 +121,6 @@ class MyApp extends StatelessWidget {
|
||||
'/login': (context) => const LoginPage(),
|
||||
'/main': (context) => const MainPage(),
|
||||
},
|
||||
home: _buildHome(),
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -143,7 +143,7 @@ packages:
|
||||
source: sdk
|
||||
version: "0.0.0"
|
||||
flutter_animate:
|
||||
dependency: transitive
|
||||
dependency: "direct main"
|
||||
description:
|
||||
name: flutter_animate
|
||||
sha256: "7befe2d3252728afb77aecaaea1dec88a89d35b9b1d2eea6d04479e8af9117b5"
|
||||
|
||||
@@ -12,6 +12,7 @@ dependencies:
|
||||
|
||||
# UI 组件库
|
||||
shadcn_ui: ^0.52.1
|
||||
flutter_animate: ^4.5.0
|
||||
|
||||
# 状态管理
|
||||
provider: ^6.1.1
|
||||
|
||||
Reference in New Issue
Block a user