vscode/cursor 配置 保存自动清除未引用 import（Flutter / 前端通用）

本文说明 VS Code / Cursor 工作区中 .vscode/settings.json 的一项语言无关配置：保存文件时自动整理 import，移除未使用的引用。

该配置并非 Flutter 专属——只要对应语言的 Language Server 支持 Organize Imports，保存时就会生效。本仓库同时涉及 Flutter、Vue、TypeScript 等多种文件类型，因此这一配置对前端及多语言项目均适用。

配置位置

工作区配置文件：.vscode/settings.json

核心片段：

"editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
}

工作原理

editor.codeActionsOnSave 是 VS Code / Cursor 的内置能力，在保存文件时触发 Language Server 提供的 Code Action。

source.organizeImports 表示执行「整理 import / 整理导入」：

行为	说明
删除未使用的 import	移除文件中已不再引用的模块、包、组件
排序 / 分组	按各语言规范重新排列 import 语句

值为 "explicit" 的含义：只有在工作区或用户配置中显式写入该项时，保存才会触发；不会依赖某个扩展的隐式默认行为。本仓库已在 .vscode/settings.json 中启用。

保存文件 (Cmd/Ctrl + S)
        ↓
editor.codeActionsOnSave 触发
        ↓
当前文件的 Language Server 执行 Organize Imports
        ↓
未使用的 import 被移除，剩余 import 被整理

适用语言与扩展

以下为常见支持情况（取决于是否安装对应语言扩展）：

语言 / 框架	典型文件	所需扩展	整理对象
Dart / Flutter	.dart	Dart / Flutter	import 'package:...'
TypeScript	.ts、.tsx	内置或 TypeScript 扩展	import { ... } from '...'
JavaScript	.js、.jsx、.mjs	内置或 TypeScript 扩展	import / require（视 LSP 能力）
Vue	.vue、.uvue	Vue - Official (Volar)	<script> 中的 import
uni-app x 等	.uts	对应 TS 语言支持	按 TypeScript 规则处理
Python	.py	Pylance	import / from ... import
Java / Kotlin	.java、.kt	Extension Pack for Java 等	import 语句
Go	.go	Go 扩展	import 块

同一工作区里只要打开上述类型的文件并保存，都会走同一套 codeActionsOnSave 配置，无需为每种语言单独写规则。

本仓库 settings.json 中的 files.associations 也体现了多语言场景：

"files.associations": {
    "*.vue": "vue",
    "*.uvue": "vue",
    "*.uts": "typescript",
    "*.dbclient-js": "javascript"
}

这些关联让 VS Code 为 Vue、TS、JS 文件选用正确的 Language Server，从而使 source.organizeImports 在保存时能够正确生效。

各语言示例

Flutter / Dart

保存前：

import 'package:flutter/material.dart';
import 'package:dio/dio.dart'; // 未使用

void main() {
  runApp(const MyApp());
}

保存后：

import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

TypeScript / JavaScript

保存前：

import { useState } from 'react';
import axios from 'axios'; // 未使用

export function Counter() {
  const [n, setN] = useState(0);
  return n;
}

保存后：

import { useState } from 'react';

export function Counter() {
  const [n, setN] = useState(0);
  return n;
}

Vue

保存前：

<script setup lang="ts">
import { ref } from 'vue';
import axios from 'axios'; // 未使用

const count = ref(0);
</script>

保存后：

<script setup lang="ts">
import { ref } from 'vue';

const count = ref(0);
</script>

与「包管理器未使用依赖」的区别

本配置处理的是源码文件顶部的 import 语句，不会修改依赖清单文件：

类型	本配置是否处理	对应清单文件
未使用的 import	✅ 保存时自动清理	—
未使用的 npm 包	❌ 否	package.json
未使用的 Dart 包	❌ 否	pubspec.yaml
未使用的 Python 包	❌ 否	requirements.txt / pyproject.toml

如需清理清单里声明但未使用的 package，需借助 depcheck、dart pub deps 等工具，或手动维护。

前置条件

1. 使用 VS Code 或 Cursor 以工作区根目录打开项目，加载 .vscode/settings.json。
2. 目标语言已安装对应 Language Server 扩展（见上表）。
3. 文件扩展名 / files.associations 能被编辑器正确识别。

Flutter 项目额外说明

• 存在 pubspec.yaml 且已执行 flutter pub get。
• analysis_options.yaml 中 flutter_lints 的 unused_import 规则会在编辑时提示问题；保存时本配置会自动修复，两者互补。

手动触发

除保存自动执行外，也可手动整理：

• 命令面板：Organize Imports（中文：「整理 import」/「整理导入」）
• 快捷键（macOS 默认）：Option + Shift + O

完整工作区配置参考

{
    "java.configuration.updateBuildConfiguration": "interactive",
    "files.associations": {
        "*.dbclient-js": "javascript",
        "*.vue": "vue",
        "*.uvue": "vue",
        "*.uts": "typescript",
        "__bit_reference": "cpp",
        "__hash_table": "cpp",
        "__split_buffer": "cpp",
        "__tree": "cpp",
        "array": "cpp",
        "deque": "cpp",
        "forward_list": "cpp",
        "initializer_list": "cpp",
        "ios": "cpp",
        "set": "cpp",
        "string": "cpp",
        "string_view": "cpp",
        "unordered_map": "cpp",
        "vector": "cpp"
    },
    "editor.codeActionsOnSave": {
        "source.organizeImports": "explicit"
    },
    "compile-hero.disable-compile-files-on-did-save-code": false
}

配置块	作用范围
editor.codeActionsOnSave	全局通用：所有支持 Organize Imports 的语言
files.associations	指定 Vue、TS、JS 等文件的 Language Server
java.configuration.*	仅 Java 项目
compile-hero.*	仅 Compile Hero 扩展

验证步骤

1. 在任意支持的语言文件中添加一行未使用的 import。
2. 保存文件（Cmd + S / Ctrl + S）。
3. 确认未使用的 import 已被删除。

若未生效，请检查：

• 是否以工作区根目录打开项目
• 该语言扩展是否已安装并正常运行
• 文件类型是否被 Language Server 识别（可参考 files.associations）
• 用户级设置是否覆盖了工作区配置（工作区配置优先级更高）

参考链接

• VS Code：Save Actions / Code Actions on Save
• Dart：Organize imports
• TypeScript in VS Code