---
title: Flutter 应用开发环境问题记录
date: '2025-12-08'
summary: 记录 Flutter 开发中遇到的环境、依赖与平台配置问题及处理过程。
lang: zh
category: Engineering
legacy_url: https://dozybot001.github.io/2025/12/08/2025-12-08-flutter-troubleshooting/
---

### 前言

正在用 Flutter 开发一个应用，IDE 为 WebStorm，配置环境时几经波折，特此记录。

### Flutter 安装

Flutter 官方建议通过 VSCode 自动安装 Flutter 扩展，但由于未知原因，出现报错，所以只能手动安装，https://docs.flutter.dev/install/manual 。

1. 下载 Flutter SDK
2. 解压到某个地址，复制内部 bin 文件夹的路径
3. 按住 Win+Fn+B，或者直接搜索 “编辑系统环境变量”
4. 点击 “环境变量”，双击 Path，添加 bin 文件夹路径，并上移到顶部

在 IDE 中执行：

```bash
flutter create MyApp
cd MyApp
```

打开 pubspec.yaml 配置依赖，然后清除缓存重新拉取依赖：

```bash
flutter clean
flutter pub get
```

在 lib 文件夹中设计你的应用。

之后输入：

```bash
flutter run
```

选择部署设备，即可预览效果。

### Windows 开发环境

完成设计后，要将 flutter 应用打包成 Windows 安装文件。运行：

```bash
flutter doctor
```

可以看到当前配置了哪些开发环境。

#### Visual Studio

Windows 开发环境的配置，需要下载 Visual Studio，打开后选择 “使用 C++ 的桌面开发”，勾选必要组件后下载并安装。

![](/blog/assets/2025-12-08-flutter-troubleshooting/20251208131941419.png)

环境配置好后，运行：

```bash
flutter build windows
```

在`build\windows\x64\runner\Release\`生成包文件。

#### Inno Setup Compiler 打包

将源码推送到 Github 后，点击仓库页右边栏的 Create a new Release 发布，可以将整个 Release 文件夹压缩成 .zip 上传到 Assets，也可以用 Inno Setup Compiler 打包成 .exe 程序。

Inno Setup Compiler 安装：https://jrsoftware.org/isdl.php

打开后新建脚本 with the Script Wizard，按步骤创建脚本后执行，如遇到打包的 .exe 文件不能执行，常见原因是文件结构错误，打开脚本检查：

```Script
[Files]
Source: "...Release\{#MyAppExeName}"; DestDir: "{app}"; Flags: ignoreversion
Source: "...Release\app_links_plugin.dll"; DestDir: "{app}"; Flags: ignoreversion
Source: "...Release\flutter_secure_storage_windows_plugin.dll"; DestDir: "{app}"; Flags: ignoreversion
Source: "...Release\flutter_windows.dll"; DestDir: "{app}"; Flags: ignoreversion
Source: "...Release\url_launcher_windows_plugin.dll"; DestDir: "{app}"; Flags: ignoreversion
Source: "...Release\data\*"; DestDir: "{app}\data"; Flags: ignoreversion recursesubdirs createallsubdirs
; NOTE: Don't use "Flags: ignoreversion" on any shared system files
```

注意 data 文件夹内的文件打包后也要放在 data 文件夹内，`DestDir: "{app}\data"`。

### Android 开发环境

运行：

```bash
flutter doctor
```

检查环境配置。

#### Android Studio

Android 开发需要安装 Android Studio，https://developer.android.com/studio?hl=zh-cn

一并下载 Android Studio 安装包和下面的命令行工具。

#### Android SDK

安装 Android Studio 后它会提示你下载并安装 Android SDK，然而下载过程可能十分艰难，动不动就握手失败，安装完成后他会提示你有哪些安装失败了，点击 Show Details，看哪些文件下载失败，他会给出 https://dl.google.com/android/repository ... 开头的链接 . 直接手动打开浏览器下载。之后将下载的文件放在`C:\Users\{UserName}\AppData\Local\Android\Sdk`文件夹中。

注意：
1. 通过 Android Studio 下载 SDK 失败的文件，也会创建文件夹，里面会存在`.install\.installData`文件。
2. 通过浏览器手动下载好压缩包后，将解压缩出来的文件夹打开，进入有大量不同类型文件的目录，复制所有文件，将其放在与 .install 文件夹同级的目录。
   ![](/blog/assets/2025-12-08-flutter-troubleshooting/20251208140758131.png)
3. 之后再运行 Android Studio 检查，它还会提示缺失 SDK，如果文件位置正确，再走一遍下载流程，Show Details 会提示没有文件需要更新，之后再打开 Android Studio 就不会提示缺失 SDK 了。

完整 SDK 文件夹结构：

```
Sdk
├─ .knownPackages
├─ .temp
├─ build-tools
│  └─ 36.1.0
│     ├─ aapt.exe
│     ...
├─ cmdline-tools
│  └─ latest
│     ├─ bin
│     ...
├─ emulator
│  ├─ android-info.txt
│  ...
├─ licenses
│  ├─ android-googletv-license
│  ...
├─ platform-tools
│  ├─ adb.exe
│  ...
├─ platforms
│  └─ android-36
│     ├─ android-stubs-src.jar
│     ...
└─ sources
   └─ android-36
      ├─ ActiveProcessingPicture.java
      ...

```

将下载的命令行工具解压缩也放在了这个目录：参考 https://developer.android.com/tools/sdkmanager?hl=zh-cn

> 1. 从 Android Studio 页面下载最新的命令行工具软件包，然后提取该软件包。
> 2. 将解压缩的 cmdline-tools 目录移至您选择的新目录，例如 android_sdk。这个新目录就是您的 Android SDK 目录。
> 3. 在解压缩的 cmdline-tools 目录中，创建一个名为 latest 的子目录。
> 4. 将原始 cmdline-tools 目录内容（包括 lib 目录、bin 目录、NOTICE.txt 文件和 source.properties 文件）移动到新创建的 latest 目录中。现在，您就可以从这个位置使用命令行工具了。


再次运行：

```bash
flutter config --android-sdk "C:\Users\derek\AppData\Local\Android\Sdk" #告诉终端 SDK 位置
flutter doctor
```

会提示环境已配置好：

![](/blog/assets/2025-12-08-flutter-troubleshooting/20251208141704694.png)

运行：

```bash
flutter build apk --split-per-abi
```

构建 Android APK 文件。若在打包过程中依旧出现下载错误，可以打开 `android\build.gradle.kts` ，修改顶部的repositories，在google()上方添加阿里云镜像：

```bash
maven { url 'https://maven.aliyun.com/repository/google' }
maven { url 'https://maven.aliyun.com/repository/public' }
```

然后清理缓存并重试：

```bash
flutter clean
flutter pub get
flutter build apk --split-per-abi
```

#### Web 开发环境

输入代码检查Web环境是否开启：

```bash
flutter devices
```

如果能看到 Chrome 或 Edge，说明环境已经准备好了，输入：

```bash
flutter run -d chrome
```

直接在浏览器预览效果。

输入：

```bash
flutter build web --release --base-href "/{your_repository_name}/"
```

打包生成网页文件，这是纯静态网页，可以直接部署在Github Pages上，{your_repository_name}是Github仓库名称，一定要加后面这一串，因为Flutter 默认打包出来的网页，认为自己部署在网站的根目录（例如 https://www.example.com/ ）， 但是，GitHub Pages 实际上是部署在子路径下的：https://your_github_name.io/{your_repository_name}/ 。当打开网页时，浏览器会去根目录找 main.dart.js 等文件，结果找不到（404错误），所以屏幕一片空白。你可以按 F12 打开浏览器控制台，肯定满屏红色的 404 Not Found。

#### MacOS 和 IOS

MacOS 和 IOS的开发都需要一台 Mac 电脑，如果不想买台白苹果可以研究研究黑苹果。恰好今天在路边捡到一台MacBook Air 2020 M1...