在 VS Code 里开发 Flutter 应用


Installation and setup

根据 编辑工具设定 的指引来安装 Dart 和 Flutter 扩展(也叫做插件)。

Follow the Set up an editor instructions to install the Dart and Flutter extensions (also called plugins).


Updating the extension

扩展的更新会定期发布。默认情况下,当有可用的更新时 VS Code 会自动更新扩展。

Updates to the extensions are shipped on a regular basis. By default, VS Code automatically updates extensions when updates are available.


To install updates manually:

  1. 点击侧边栏的 Extensions 按钮。

    Click the Extensions button in the Side Bar.

  2. 如果 Flutter 扩展显示有可用更新,点击更新按钮,然后重载。

    If the Flutter extension is shown with an available update, click the update button and then the reload button.

  3. 重启 VS Code。

    Restart VS Code.


Creating projects


There are a couple ways to create a new project.


Creating a new project

通过 Flutter 入门应用模板新建 Flutter 项目:

To create a new Flutter project from the Flutter starter app template:

  1. 打开命令面板(Ctrl+Shift+P (macOS 用 Cmd+Shift+P))。

    Open the Command Palette (Ctrl+Shift+P (Cmd+Shift+P on macOS)).

  2. Select the Flutter: New Application Project command and press Enter.

打开命令面板(`Ctrl`+`Shift`+`P` (macOS 用 `Cmd`+`Shift`+`P`))。选择 **Flutter: New Application Project** 命令然后按 `Enter`。
  1. 输入你想要的项目名

    Enter your desired Project name.

  2. 选择项目地址

    Select a Project location.


Opening a project from existing source code

打开现有 Flutter 项目:

To open an existing Flutter project:

  1. 在 IDE 主窗口点击 File > Open

    Click File > Open from the main IDE window.

  2. 选择存放现有 Flutter 源代码文件的目录。

    Browse to the directory holding your existing Flutter source code files.

  3. 点击 Open

    Click Open.


Editing code and viewing issues

Flutter 扩展执行代码分析,它提供:

The Flutter extension performs code analysis that enables the following:

  • 语法高亮。

    Syntax highlighting

  • 基于丰富输入分析的代码补全。

    Code completions based on rich type analysis

  • 导航到类型声明(Go to DefinitionF12)和查找类型引用(Find All ReferencesShift+F12)。

    Navigating to type declarations (Go to Definition or F12), and finding type usages (Find All References or Shift+F12)

  • 查看所有当前代码问题(View > ProblemsCtrl+Shift+M (macOS 用 Cmd+Shift+M))。所有问题分析都会在 Problems 面板展示:
    Problems pane

    Viewing all current source code problems (View > Problems or Ctrl+Shift+M (Cmd+Shift+M on macOS)) Any analysis issues are shown in the Problems pane:
    Problems pane


Running and debugging

在 IDE 主窗口点击 Run > Start Debugging 或按 F5 开启调试。

Start debugging by clicking Run > Start Debugging from the main IDE window, or press F5.


Selecting a target device

当一个 Flutter 项目在 VS Code 中打开,你会在状态栏看到一些 Flutter 特有项,包括 Flutter SDK 版本和设备名称(或者无设备信息):

When a Flutter project is open in VS Code, you should see a set of Flutter specific entries in the status bar, including a Flutter SDK version and a device name (or the message No Devices):

VS Code status bar

Flutter 扩展会自动选择上次连接的设备。然而,如果你有多个设备/模拟器连接,点击状态栏的 device 查看屏幕顶部的选择列表。选择你要用来运行或调试的设备。

The Flutter extension automatically selects the last device connected. However, if you have multiple devices/simulators connected, click device in the status bar to see a pick-list at the top of the screen. Select the device you want to use for running or debugging.


Run app without breakpoints

  1. 在 IDE 主窗口点击 Run > Start Without Debugging,或者按 Ctrl+F5,状态栏变橙色说明你正处于调试模式。
    Debug console

    Click Run > Start Without Debugging in the main IDE window, or press Ctrl+F5. The status bar turns orange to show you are in a debug session.
    Debug console


Run app with breakpoints

  1. 如果需要,在源代码中设置断点。

    If desired, set breakpoints in your source code.

  2. 在 IDE 主窗口点击 Run > Start Debugging 或按 F5

    Click Run > Start Debugging in the main IDE window, or press F5.

    • 左侧的调试侧边栏显示堆栈帧和变量。

      The left Debug Sidebar shows stack frames and variables.

    • 底部的调试控制台面板显示输出的日志详情。

      The bottom Debug Console pane shows detailed logging output.

    • 调试基于默认的配置。也可以通过点击调试侧边栏顶部的齿轮创建 launch.json 文件自定义调试。你可以修改里面的值。

      Debugging is based on a default launch configuration. To customize, click the cog at the top of the Debug Sidebar to create a launch.json file. You can then modify the values.

以调试 (debug)、性能 (profile) 或发布 (release) 模式运行应用

Run app in debug, profile, or release mode

Flutter 提供了很多种不同的构建模式运行你的应用,更多内容请参考文档 Flutter 的构建模式

Flutter offers many different build modes to run your app in. You can read more about them in Flutter’s build modes.

  1. 打开 VS Code 里的 launch.json 文件

    Open the launch.json file in VS Code.

    如果你没有 launch.json 文件,请到 VS Code 的 Run 视图,点击 create a launch.json file 创建。

    If you do not have a launch.json file, go to the Run view in VS Code and click create a launch.json file.

  2. configurations 部分,修改 flutterMode 属性值为你想要的构建模式即可。

    In the configurations section, change the flutterMode property to the build mode you want to target.

    • 举个例子,如果你希望在调试模式下运行,你的 launch.json 文件应该类似下面这样:

      For example, if you want to run in debug mode, your launch.json might look like this:

      "configurations": [
         "name": "Flutter",
         "request": "launch",
         "type": "dart",
         "flutterMode": "debug"
  3. Run 视图里运行你的应用。

    Run the app through the Run view.


Fast edit and refresh development cycle

Flutter 提供一流的开发周期,通过 Stateful Hot Reload 特性使你在几乎修改代码的同时就能看到变化。详情请看 使用热重载

Flutter offers a best-in-class developer cycle enabling you to see the effect of your changes almost instantly with the Stateful Hot Reload feature. See Using hot reload for details.


Advanced debugging


You might find the following advanced debugging tips useful:


Debugging visual layout issues

在调试会话期间,命令面板Flutter inspector 会添加一些额外的调试命令,包括:

During a debug session, several additional debugging commands are added to the Command Palette and to the Flutter inspector. When space is limited, the icon is used as the visual version of the label.

切换 Baseline 绘制Toggle Baseline Painting Baseline painting icon

每个 RenderBox 在底部绘制一条线。

Causes each RenderBox to paint a line at each of its baselines.

切换重绘 RainbowToggle Repaint Rainbow Repaint rainbow icon


Shows rotating colors on layers when repainting.

切换慢模式横幅Toggle Slow Animations Slow animations icon
减慢动画以启用视觉检查。Slows down animations to enable visual inspection.
切换 debug 模式横幅显示Toggle Debug Mode Banner Debug mode banner icon

在运行调试构建时隐藏 debug 模式的横幅 (banner)。

Hides the debug mode banner even when running a debug build.


Debugging external libraries

默认情况下,Flutter 扩展禁止调试外部库。启用步骤:

By default, debugging an external library is disabled in the Flutter extension. To enable:

  1. 选择 Settings > Extensions > Dart Configuration

    Select Settings > Extensions > Dart Configuration.

  2. 勾选 Debug External Libraries 选项。

    Check the Debug External Libraries option.

Flutter 代码编辑提示

Editing tips for Flutter code

如果你有其他我们应该提供的代码提示建议,请 [告诉我们][]!

If you have additional tips we should share, let us know!


Assists & quick fixes

代码辅助功能是特定代码标识符相关的代码修改。当光标放在 Flutter widget 上时,黄色灯泡图标会指示可用的修改,可以通过点击灯泡进行修改,或者使用快捷键 Ctrl+. (macOS 用 Cmd+.),如图所示:

Assists are code changes related to a certain code identifier. A number of these are available when the cursor is placed on a Flutter widget identifier, as indicated by the yellow lightbulb icon. The assist can be invoked by clicking the lightbulb, or by using the keyboard shortcut Ctrl+. (Cmd+. on Mac), as illustrated here:

Code assists


Quick fixes are similar, only they are shown with a piece of code has an error and they can assist in correcting it.

Widget 嵌套辅助

Wrap with new widget assist

当你有个 widget 想包装进一个容器 widget 时,例如你想把 widget 放入一个 Row 或者 Column

This can be used when you have a widget that you want to wrap in a surrounding widget, for example if you want to wrap a widget in a Row or Column.

Widget 列表嵌套辅助

Wrap widget list with new widget assist

和上面的辅助类似,但它嵌套的是一个 widget 的列表,而不是单个的 widget。

Similar to the assist above, but for wrapping an existing list of widgets rather than an individual widget.

child 和 children 转换辅助

Convert child to children assist

将 child 转换成 children,并且把参数值写进一个 list。

Changes a child argument to a children argument, and wraps the argument value in a list.

Convert StatelessWidget to StatefulWidget assist
Changes the implementation of a StatelessWidget to that of a StatefulWidget, by creating the State class and moving the code there.

StatelessWidget 到 StatefulWidget 的转换
创建 State 类并将代码移动过去,可以将 StatelessWidget 的实现更改为 StatefulWidget




Snippets can be used to speed up entering typical code structures. They are invoked by typing their prefix, and then selecting from the code completion window:


Flutter 扩展包含以下片段:

The Flutter extension includes the following snippets:

  • 前缀 stless:创建一个 StatelessWidget 子类。

    Prefix stless: Create a new subclass of StatelessWidget.

  • 前缀 stful:创建一个 StatefulWidget 子类,并且和 State 子类关联。

    Prefix stful: Create a new subclass of StatefulWidget and its associated State subclass.

  • 前缀 stanim:创建一个 StatefulWidget 子类,并且把包含字段初始化的 State 子类和一个 AnimationController 关联。

    Prefix stanim: Create a new subclass of StatefulWidget, and its associated State subclass including a field initialized with an AnimationController.

你也可以通过在 命令面板 执行Configure User Snippets来自定义片段。

You can also define custom snippets by executing Configure User Snippets from the Command Palette.


Keyboard shortcuts

Hot reload
During a debug session, clicking the Hot Reload button on the Debug Toolbar, or pressing Ctrl+F5 (Cmd+F5 on macOS) performs a hot reload.

调试期间,在 调试工具栏 点击 热重载 (Hot Reload) 按钮,或者按 Ctrl+F5(macOS 用 Cmd+F5)执行热重载。

键位绑定可以在 命令板 中使用 Open Keyboard Shortcuts 命令进行调整。

Keyboard mappings can be changed by executing the Open Keyboard Shortcuts command from the Command Palette.


Hot reload vs. hot restart

热重载的工作原理是将更新后的代码注入 Dart VM(虚拟机)。不仅包括添加新类,还包括添加方法和字段到已有的类中。但有些类型的代码是无法被热重载的:

Hot reload works by injecting updated source code files into the running Dart VM (Virtual Machine). This includes not only adding new classes, but also adding methods and fields to existing classes, and changing existing functions. A few types of code changes cannot be hot reloaded though:

  • 全部变量的初始化

    Global variable initializers

  • 静态变量的初始化

    Static field initializers

  • 应用的 main() 方法

    The main() method of the app

对于这些更改,你无需结束调试过程而直接热重启 (hot restart) 你的应用。要执行热重启,执行 命令面板Flutter:热重启命令,或者按 ``Ctrl+Shift+F5 (在 macOS 上使用 Cmd+Shift+F5)。

For these changes, fully restart your application without having to end your debugging session. To perform a hot restart, run the Flutter: Hot Restart command from the Command Palette, or press Ctrl+Shift+F5(Cmd+Shift+F5 on macOS).




Known issues and feedback

所有已知 bug 在这个 issue 列表中记录: Dart 和 Flutter 扩展 GitHub issue 追踪

All known bugs are tracked in the issue tracker: Dart and Flutter extensions GitHub issue tracker.

我们非常欢迎 bugs/issues 和特性请求的反馈。在提交新 issue 之前:

We welcome feedback, both on bugs/issues and feature requests. Prior to filing new issues:

  • 在 issue 列表中查找看该问题是否已被记录。

    Do a quick search in the issue trackers to see if the issue is already tracked.

  • 确保你已经 更新 最新版本插件。

    Make sure you are up to date with the most recent version of the plugin.

提交新 issue 时,请包含 flutter doctor 输出。

When filing new issues, include flutter doctor output.