Kotlin 開発を VSCode + Docker で始めるときに最低限やるべき設定まとめ

# 初めに

現在の職場では、Kotlin の開発を VSCode と Docker を使って行っています。  
ただ、実際にこの構成で開発環境を整えようとすると、意外とすんなりいかない部分も多くありました。

特に困ったのが、Kotlin 標準ライブラリや Spring Boot のような外部ライブラリの定義ジャンプが  VSCode 上でうまく動かず、「定義が読み込めません」といったエラーが頻繁に発生することでした。

この問題は、正直なところ1年以上ちゃんと解消されずに放置されていた部分でもあります。

この記事では、そういった経験を踏まえて、Kotlin × VSCode × Docker で  
**安定して補完・定義ジャンプ・開発ができる環境を構築する方法**をまとめています。

同じような環境で悩んでいる方の参考になれば嬉しいです。

---

# 前提事項

この記事は、以下のような前提のもとで書かれています。

- IntelliJ IDEA の有料版（Ultimate）が使用できない  
  → よって、Kotlin 開発には VSCode を使用しています
- 開発環境は Docker 上で構築し、ホスト環境には極力依存させたくない
- プロジェクトは Kotlin DSLのGradle（`build.gradle.kts`）で構成されている

---

# ⚠️実はそれだけじゃ動かなかった

私は最初、VSCode + Docker の環境で Kotlin の開発を行う場合、  
「Gradle と JDK が入った Docker 環境を用意して、Kotlin Language Server（fwcd）を入れれば動くだろう」  
と思っていました。

ですが、実際にはそう簡単にはいきませんでした。

例えば、`build.gradle.kts` で依存を追加しているのに、  
VSCode 上ではそれらのクラスに対して「定義ジャンプ」が効かなかったり、  
標準ライブラリでさえ補完が出ず、赤い波線が出続けることもありました。

---

# 🔍外部ライブラリに定義ジャンプできない問題とその背景

以下の Issue にあるように、**Kotlin Language Server（fwcd） は `.jar` 内にあるクラスを見つけたとしても、  
その中身の `.java` ソースコードを探し当てるのに失敗するケースがあります。

📎 [Issue #410 - Go-to-definition not working for external java jar](https://github.com/fwcd/kotlin-language-server/issues/410)

実際に記録されたエラーログの一部は以下のとおりです：

```:#410にあるエラー
async2    Found declaration descriptor Lazy Java class org.apache.arrow.flight.FlightServer
async2    Finished in 11 ms
The following file kls:file:///Users/aiguofer/.gradle/caches/modules-2/files-2.1/org.apache.arrow/flight-core/10.0.1/626dcd8fb0f467cb93ca17e8fcfee1bb383b96d3/flight-core-10.0.1.jar!/org/apache/arrow/flight/FlightServer.kt is missing, ignoring from the results.
```

このログから読み取れる **Kotlin Language Server（fwcd）** の挙動は以下の通りです：

- KLS は `FlightServer` クラスのシンボル情報（型や定義）までは正常に取得できている
- しかし、ソースコードを参照しようとした際に `.kt` ファイルを探しにいってしまう
- 実際には `FlightServer` は Java で書かれているため、存在するのは `.java` ファイル
- `.kt` ファイルが見つからず、KLS は「該当ソースなし」と判断して結果から除外してしまう

つまり、**KLS は Java 実装クラスであっても Kotlin ソース（.kt）を前提に参照しようとするため、`.java` のソースコードが正しく取得されないケースがある**ということです。

---

# 💡現時点での回避策

この問題に対して、**Kotlin Language Server（fwcd）** 側では以下のような対処が検討されてきました。

📎 [PR #439 - Use eclipse gradle plugin to get classpath with sources](https://github.com/fwcd/kotlin-language-server/pull/439)

この PR では、Gradle の Eclipse プラグインを利用して `.classpath` を生成し、  
その中に含まれる sources.jar 付きの依存情報を **Kotlin Language Server（fwcd） に渡すことで、  
**Kotlin Language Server（fwcd）** が外部ライブラリのソースコードを正しく認識できるようにする提案がされています。

```gradle:Eclipse 用のプロジェクトファイル生成する設定
plugins {
    // その他の設定
    eclipse
}

eclipse {
    classpath {
        downloadSources = true
    }
}

```

---

## ❗️ただし Kotlin DSL では eclipse プラグインが使えない

ここで問題になるのが、Kotlin DSL（`build.gradle.kts`）では以下のようなエラーが発生してしまうことです。

```
Cannot access 'downloadSources': it is private in 'EclipseClasspath'
```

これは、`eclipse.classpath.downloadSources = true` のような記述が Kotlin DSL では非公開（internal）扱いになっているためで、**Kotlin DSL 環境ではこの設定を使えません。**

---

## ✅ 代替手段：`idea` プラグインで sources.jar を取得する

Kotlin DSL を使っている場合、`eclipse` プラグインの `downloadSources = true` はサポートされていないため使えません。

その代替手段として有効なのが、`idea` プラグインを使う方法です。  
これにより、Kotlin DSL 環境でも `sources.jar` を自動で取得できるようになります。

```gradle:IntelliJ IDEA 用のプロジェクトファイルと sources.jar を生成する設定
plugins {
    kotlin("jvm") version "2.1.10"
    id("idea")
}

idea {
    module {
        isDownloadSources = true
        isDownloadJavadoc = true
    }
}
```

この設定を加えたうえで、以下のコマンドを実行します。

```bash
./gradlew idea --no-configuration-cache
```

> ❗️`--no-configuration-cache` を付ける理由：
>
> Gradle の設定キャッシュが有効になっていると、`idea` タスクが古い構成を使い回してしまい、  
> `sources.jar` のダウンロード設定が正しく反映されないことがあります。  
> そのため、**初回実行時や設定変更後は `--no-configuration-cache` を付けておくのが確実です。**

このコマンドを実行すると、IntelliJ IDEA 用の `.iml` ファイルや依存ライブラリ情報と一緒に、`dependencies` に含まれる各ライブラリの `sources.jar` や `javadoc.jar` もダウンロードされるようになります。

Kotlin Language Server（KLS）は、このキャッシュされた `sources.jar` をもとに、外部ライブラリのソースコードへ補完や定義ジャンプが可能になります。

---

## 🔁 応急処置的な対応策

- Mavenなどから手動で `sources.jar` を取得し、`libs/` ディレクトリに配置する  

---

# ✅ まとめ

**VSCode + Docker + Kotlin DSL** の構成で Kotlin 開発を行う場合、**Kotlin Language Server（KLS）**で外部ライブラリのソースコードが参照できない問題が発生することがあります。

この問題に対して、次のような対応が有効です：

- `eclipse` プラグインで `.classpath` を生成し、`sources.jar` を含める  
  - ただし、この方法は Kotlin DSL（`build.gradle.kts`）では設定が制限されており、利用できない  
- `idea` プラグインを `build.gradle.kts` に追加し、`sources.jar` と `javadoc.jar` の取得を有効にする  
- `./gradlew idea --no-configuration-cache` を実行して依存ライブラリのソースを取得する  
- 取得された `sources.jar` により、KLS で外部ライブラリの補完や定義ジャンプが可能になる

**IntelliJ（Ultimate）**が使えない環境でも、`idea` プラグインを活用することで、  
VSCode 上で快適な Kotlin 開発環境を構築することができます。

---


この記事が、同じような構成で開発を進めている方の助けになれば幸いです。
実際の開発環境は、下記を参考にしてください。

https://github.com/ht-0328/docker-kotlin-dev