今天開始換由巨頭微軟力推的套件管理器 vcpkg 上場，介紹怎麼使用 vcpkg 搭配 CMake 專案。

我們的目標：

1. 安裝 vcpkg
2. 導入兩個第三方函式庫 fmt 和 nlohmann_json
3. 連結 CMake 專案
4. 編譯，執行，確認，收工。

我的測試環境如下

• Windows 11 + Visual Studio 2022（MSVC）
• macOS 26 + Xcode 26（Apple Clang）
• Debian 13 + GCC
• vcpkg 2026-xx-xx
• CMake 3.31

步驟一：安裝 vcpkg

其實微軟的官方教學頁面就寫得很清楚了
https://learn.microsoft.com/zh-tw/vcpkg/get_started/get-started

我很快的講一遍：vcpkg 安裝法是直接 clone 它的 GitHub repo，再跑 bootstrap 腳本。

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

如果是 macOS/Linux 就就改跑 ./bootstrap-vcpkg.sh

bootstrap 腳本會下載一個編譯好的 vcpkg 執行檔，放在 repo 根目錄。

macOS 要先裝好 Xcode Command Line Tools，不然 bootstrap 會失敗。

然後設定兩個環境變數

1. VCPKG_ROOT : 指向你剛剛 clone 下來的 github repo 位置。
2. 把 VCPKG_ROOT 加入 PATH 環境變數。

用命令列確認一下，可以呼叫 vcpkg：

vcpkg --version

有看到版本號碼印出來就是安裝成功囉。

步驟二：建立 CMake 專案

我們一樣從最基本的迷你 CMake 專案開始，目錄結構如下：

hello-vcpkg/
├── CMakeLists.txt
└── src/
    └── main.cpp

步驟三：創建入口檔案 vcpkg.json

接著，請到專案根目錄執行以下命令：

vcpkg new --application

執行後，目錄下會多出兩個檔案：vcpkg.json 以及 vcpkg-configuration.json

hello-vcpkg/
├── vcpkg.json
├── vcpkg-configuration.json
├── CMakeLists.txt
└── src/
    └── main.cpp

vcpkg.json 這個檔案就是 vcpkg 的入口，專案要用哪些套件都寫在這裡。

步驟四：vcpkg add 添加套件

下一步，就是為專案導入 fmt 以及 nlohmann JSON 套件，請輸入以下命令：

vcpkg add port fmt nlohmann-json

指令跑完後，我們去查看 vcpkg.json 的內容，會發現多出了個兩個套件的名字：

{
  "dependencies": [
    "fmt",
    "nlohmann-json"
  ]
}

有兩個地方值得注意：

1. 套件名稱有些微差異： vcpkg 叫 nlohmann-json（連字號），Conan 叫 nlohmann_json。vcpkg 規定套件名稱只能用小寫英文、數字和連字號。套件名稱可以來這裡查 https://vcpkg.io/en/packages 。
3. 不寫版本號。 只寫了 fmt，沒有指定版本。

那用哪版本是誰決定的呢？答案在另一個檔案 vcpkg-configuration.json：

{
  "default-registry": {
    "kind": "git",
    "baseline": "dc1232a6e05dcc49703091e83743e3b4df9b9b7c",
    "repository": "https://github.com/microsoft/vcpkg"
  }
}

baseline 其實是 vcpkg repo 裡面的一個 commit。

那個 commit 當下每個套件的都有指定好的一個版本號碼。換句話說，版本是整批鎖住的，不是一個一個指定。

版本控制之後會專門寫一篇。