VSCode运行Kotlin程序教程 - 零基础配置运行环境

首先得弄明白一个根本事实：kotlinc 编译器是必须装的，VSCode 里的 Kotlin 插件仅仅是个桥接工具。没有编译器，连 println("Hello") 都跑不起来——别被“装个插件就能写”的说法误导。

很多新手装上插件后发现根本没法运行，问题就出在编译器上。下面把三种常见场景的配置要点拆开说清楚。

Code Runner 跑单个 .kt 文件：适合语法验证，但限制极多

这确实是看到输出最快的方式——前提是文件结构足够简单。它只适用于无包声明、无外部依赖、且 fun main() 是顶层函数的单个源文件。换句话说，如果你想快速验证一个语法特性，用它没问题；但凡项目稍微复杂一点，这条路就走不通了。

• 系统 PATH 里必须能找到 kotlinc。macOS 上推荐 brew install kotlin，Windows 上 choco install kotlin 最省事。手动安装的话，记得把 bin/ 目录加到 PATH 里。
• VSCode 设置里找到 kotlin.compilerPath，填绝对路径，比如 /opt/homebrew/bin/kotlinc。不能用 ~ 或环境变量——插件不吃这一套。
• 在 settings.json 中配置 Code Runner 的执行命令，关键参数是 -include-runtime，漏掉它就会遇到 NoClassDefFoundError: kotlin/jvm/internal/Intrinsics。正确配置如下：

  "code-runner.executorMap": {
    "kotlin": "cd $dir && kotlinc -include-runtime -d out.jar $fileName && ja va -jar out.jar"
  }

• fun main() 必须写在顶层，不能放在 class 里。编译后生成的类名是 FileNameKt（文件名加 Kt），不是 FileName，记牢这一点。
• 如果文件里写了 package com.example 或者使用任何外部库（比如 kotlinx.coroutines），这种方式直接报废——因为 Code Runner 根本不读取 build.gradle.kts。

Gradle 项目必须配 kotlin("jvm") 和 jvmToolchain(17)

VSCode 本身不编译 Kotlin，所有构建、依赖解析和 JVM 启动都由 Gradle 驱动。没有 build.gradle.kts，插件连源码目录都识别不了。

• 新建项目别手写配置了——终端里执行 gradle init --type kotlin-application，全自动生成。
• build.gradle.kts 至少需要这两段：

  plugins {
      kotlin("jvm") version "1.9.24"
  }
  kotlin {
      jvmToolchain(17)
  }

• jvmToolchain(17) 不能省略。不写的话，Gradle 会用自带 JDK，很容易触发 UnsupportedClassVersionError——到时候排查起来很头大。
• 别忘了声明主类：application { mainClass.set("com.example.AppKt") }。注意类名必须是 AppKt（文件名加 Kt），写成 App 会报 Could not find or load main class。
• 源码必须放到 src/main/kotlin/ 目录下。如果丢在项目根目录或别的地方，插件完全无视。

launch.json 调试总失败？别照搬 Ja va 配置

Kotlin 调试的本质是 attach 到已经启动的 JVM 进程，而不是像解释脚本那样直接执行 .kt 文件。所以直接照搬 Ja va 的 launch.json（设置 type: "ja va" 和 mainClass）经常断点不命中，让人抓狂。

• 最稳的方式：让 Gradle 启动带 JDWP 参数的 JVM。运行命令：./gradlew run --no-daemon -Dorg.gradle.debug=true。这样 VSCode 的调试器可以 attach 上去。
• 或者在 launch.json 中用 type: "shell" 启动任务：

  {
    "type": "shell",
    "request": "launch",
    "name": "Run with Gradle",
    "command": "./gradlew run --no-daemon"
  }

• 如果非要硬用 type: "ja va"，那么 mainClass 必须严格匹配编译后的类名（比如 com.example.AppKt），并且项目必须先成功构建，产生 build/libs/*.jar。
• 调试前务必检查 VSCode 的 ja va.home 和 ja va.configuration.runtimes 是否都指向 JDK 17+。两者不一致会导致 UnsupportedClassVersionError，或者断点变成灰色不可用。

为什么装了插件还是提示 “No SDK configured”

Kotlin 插件（比如 fwcd.kotlin）只提供语言服务——语法高亮、代码补全、跳转定义等——但它不自带 JDK 或编译器。它依赖 Ja va 扩展来发现运行时环境。所以提示 “No SDK configured” 并不是插件坏了，而是底层的 Ja va 扩展没有被正确配置。

• 必须在 VSCode 设置里显式填写 ja va.home，例如 /Library/Ja va/Ja vaVirtualMachines/jdk-17.jdk/Contents/Home。只靠系统环境变量 JA VA_HOME 是不够的，插件不一定认。
• 还需要在 settings.json 中补充 ja va.configuration.runtimes，否则新建 .kt 文件连语法高亮都没有：

  "ja va.configuration.runtimes": [
    {
      "name": "Ja vaSE-17",
      "path": "/Library/Ja va/Ja vaVirtualMachines/jdk-17.jdk/Contents/Home"
    }
  ]

• kotlin.compilerPath 要单独设置为 kotlinc 可执行文件的绝对路径，否则插件会报 kotlinc not found。
• 改完设置后必须重启 VSCode——插件的加载发生在启动时，改了不重启等于白改。

真正卡住人的从来不是“怎么点运行”。ja va.home、jvmToolchain、mainClass、kotlin.compilerPath 这四条路径各自独立生效，改一处并不等于全部通了。把每一条都检查到位，环境也就顺了。