创建私有Pod仓库时遭遇Classes版本目录异常错误，寻求解决方法

数据老陈

2026-5-27

Fix: "An unexpected version directory Classes was encountered" When Creating Private Pod Repo

Let’s break down what’s causing this error and how to fix it quickly. First off—this is a CocoaPods-specific error, not a git issue, so it’s tied to your pod’s directory structure or podspec configuration, not the git tag command itself (you probably hit it right after tagging, which is why you linked the two).

Common Causes & Step-by-Step Fixes

1. Double-check your podspec’s `source_files` path

The most likely culprit is a misconfigured source_files entry in your PrivateRepo.podspec. When you used pod lib create, the template sets up a Classes folder for your source code, so your podspec needs to point to it correctly.

Open your podspec and confirm this line matches your structure:

spec.source_files = 'PrivateRepo/Classes/**/*'

This tells CocoaPods to grab all files inside the Classes directory under your pod’s root folder. If the path is wrong (e.g., missing the inner pod-named folder, or pointing to the wrong level), CocoaPods gets confused and misinterprets Classes as a version directory.

2. Verify your directory structure

Make sure your repo follows the standard CocoaPods library structure. It should look like this:

PrivateRepo/
├── PrivateRepo/               # Core folder named after your pod
│   ├── Classes/               # Your source code lives here
│   │   └── YourCustomClass.swift
│   └── Resources/             # Assets/storyboards (if needed)
├── PrivateRepo.podspec        # Your podspec file
├── README.md
└── Example/                   # Auto-generated example project (optional)

If the Classes folder is in the wrong place (e.g., directly in the repo root instead of the inner PrivateRepo folder), CocoaPods will throw that "unexpected version directory" error.

3. Run local validation first

Before tagging or pushing, run this command in your repo root to catch detailed issues:

pod lib lint

This runs a full validation of your pod and gives you specific, actionable error messages—way more helpful than the generic error you saw. It’ll point you exactly to where the path or structure problem lies.

4. Clean CocoaPods cache

Sometimes cached data causes weird, unexplained issues. Clear the cache with:

pod cache clean --all

Then re-run your validation or push commands.

5. Ensure full code sync with BitBucket

Double-check you’ve committed and pushed all changes (including your updated podspec) before tagging:

git add .
git commit -m "Fix podspec paths and structure"
git push origin master
git tag 0.1.0
git push origin 0.1.0

Final Check

After fixing the podspec or directory structure, run pod lib lint again. If it passes without errors, you’ll be able to proceed with pushing your private pod to your repo without hitting that error.

内容的提问来源于stack exchange，提问作者J. Doe