Kotlin/JS Gradle插件启动服务时无法加载'@webpack-cli/serve'命令报错

报错表现 #

[webpack-cli] Unable to load '@webpack-cli/serve' command
[webpack-cli] TypeError: options.forEach is not a function

该报错在官方示例项目、IntelliJ自动创建的浏览器Kotlin JS项目中均可能出现，属于webpack-cli版本兼容问题。

修复步骤 #

1. 强制锁定webpack-cli版本
   修改项目根目录下的build.gradle.kts文件，新增Yarn版本锁定配置：

plugins {
    // 保留你原本的插件配置，无需修改
    kotlin("js") version "你的项目使用的Kotlin版本号"
}

kotlin {
    // 保留你原本的kotlin配置块内容，仅新增下方配置
    rootProject.extensions.configure<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension> {
        resolution("webpack-cli", "4.10.0")
    }
}

如果是Groovy语法的build.gradle，配置写法如下：

kotlin {
    // 保留原有配置，新增以下内容
    yarn {
        resolution "webpack-cli", "4.10.0"
    }
}

2. 清除历史缓存与锁文件

• 关闭所有正在运行的项目开发服务
• 删除项目根目录下的build文件夹
• 删除项目根目录下的yarn.lock文件，如使用NPM管理则删除package-lock.json
• 执行缓存清理命令：
  • Linux/Mac系统：./gradlew clean
  • Windows系统：gradlew.bat clean

3. 重新启动服务
   执行启动命令./gradlew jsBrowserDevelopmentRun，或直接点击IntelliJ中的项目运行按钮即可正常启动。

原理说明 #

Kotlin JS Gradle插件会自动管理webpack相关前端依赖，无需手动修改package.json或yarn.lock文件，通过Yarn强制分辨率配置即可覆盖插件默认拉取的存在兼容问题的webpack-cli版本，解决启动报错。

内容的提问来源于stack exchange，提问作者Mokyx