「共有コードが見つからない」問題をデバッグする

Almost everyone hits it once: iOS builds but Swift cannot find your shared API. Let's debug shared code not found calmly. 🛠️

First, run the Gradle framework task directly. If it fails outside Xcode, the framework never existed and Swift had nothing to link.

Swift must import the exact baseName set in build.gradle.kts. A mismatched name is the most common no-such-module error.

The Gradle build phase must run before Compile Sources. If it sits too low in the list, Swift compiles before the framework exists.

Xcode needs to know where the framework lives. Check that Framework Search Paths points at the Gradle output folder for your target.

Using CocoaPods but opened the .xcodeproj? Pods are missing. Close it and open the .xcworkspace instead.

An arm64 framework will not link into an x86 simulator. Make sure the framework was built for the same architecture as your run target.

Expand the failing step in the build log and find the first error. A later linker complaint is often just a symptom of an earlier failure.

Old artifacts can confuse the linker. A clean Gradle build plus an Xcode clean often clears a stubborn not-found error.

Only public Kotlin declarations cross to Swift. If a class is internal, Swift will not see it no matter how the framework links.

These errors look scary but are almost always config: name, path, order, or architecture. Check those four and you'll be unblocked. ✨

Let's confirm a frequent cause of this error.

You learned to debug not-found errors by checking the framework built, the import name, build-phase order, search paths, and architecture. Most fixes are config, not code. 🎉