快速入門：使用 Visual Studio（僅限 Windows）建立並發佈 NuGet 套件

在這個快速入門中，你會使用 Microsoft Visual Studio 從 .NET 類別函式庫建立一個 NuGet 套件。 接著你用命令列介面（CLI）工具將套件發佈給 nuget.org。

這個快速入門僅限 Windows 使用者使用。 如果你用的是其他平台，請使用 .NET CLI。

先決條件

• Visual Studio 2026，工作負載與 .NET 相關。

  你可以從 visualstudio.microsoft.com 免費安裝 2026 社群版，或者使用專業版或企業版。

  Visual Studio 2017 及之後版本在安裝 .NET 相關工作負載時，會自動包含 NuGet 功能。

• .NET CLI（命令列介面）。

  在 Visual Studio 2017 及之後版本，.NET CLI 會自動安裝在任何與 .NET 相關的工作負載中。 你也可以安裝 .NET SDK 來取得 .NET CLI。 .NET CLI 是使用 SDK 風格格式（及 SDK 屬性）的.NET專案所必需的。 Visual Studio 2017 及以後版本的預設 .NET 類別函式庫範本使用 SDK 屬性。

  這很重要

  如果你使用的是非 SDK 風格的專案，請依照 使用 Visual Studio（.NET Framework，Windows）建立並發佈套件中的程序來建立並發佈套件。 本文建議使用 .NET CLI。 雖然你可以透過使用 NuGet CLI 發佈任何 NuGet 套件，但本文中的一些步驟是針對 SDK 風格專案及 .NET CLI 的專屬。 NuGet CLI 用於 非 SDK 風格專案（通常.NET Framework 專案）。

• nuget.org 上有 免費帳號。您必須先註冊並確認帳號，才能上傳 NuGet 套件。

• NuGet CLI。 你可以從 nuget.org 下載來安裝。把 nuget.exe 檔案加入合適的資料夾，然後把那個資料夾加入你的 PATH 環境變數。

建立類別庫專案

你可以使用現有的 .NET 類別函式庫專案來製作你想打包的程式碼，或者你也可以透過以下步驟建立一個：

1. 在Visual Studio中，選擇 File>New>Project/Solution。

2. 在 「建立新專案 」視窗中，進入搜尋框並輸入 類別函式庫。

3. 在產生的專案範本清單中，選擇符合以下條件的 類別函式庫 範本：

   • 描述用於建立一個以 .NET 或 .NET Standard 為目標的類別庫的專案
   • 擁有 C# 標籤

   選取 下一步。

4. 在配置你的新專案 視窗中，為專案名稱，輸入AppLogger，然後選擇下一步。

5. 在 「附加資訊 」視窗中，選擇適當的框架 值，然後選擇 「建立」。

   如果你不確定要選哪個框架，最新的是個不錯的選擇，之後也可以輕鬆更換。 關於該使用哪個框架的資訊，請參閱「何時選擇netx.0」與「netstandard」。

6. （可選）在這個快速入門階段，你不需要為 NuGet 套件寫額外的程式碼，因為模板類別函式庫就足以建立套件。 不過，如果你想在套件中加入一些功能性程式碼，請包含以下程式碼：

   namespace AppLogger
   {
       public class Logger
       {
           public void Log(string text)
           {
               Console.WriteLine(text);
           }
       }
   }
   

設定套件屬性

建立專案後，你可以依照以下步驟設定 NuGet 套件的屬性：

1. 在 方案總管 中，選擇你的project，然後選擇 Project><project-name> 屬性，其中 <project-name> 是你的project名稱。

2. 展開 Package 節點，然後選擇 General。

   Package節點僅在 Visual Studio 中出現於 SDK 風格專案中。 如果你目標是非 SDK 類型的專案（通常是 .NET Framework 專案），可以選擇 migrate the project，或參考 使用 Visual Studio（.NET Framework， Windows） 建立並發佈套件以獲得逐步說明。

   

3. 對於 包裹 ID，請為你的包裹設定一個獨特的 ID。

   這很重要

   你必須給套件一個在你使用的主機間唯一的識別碼，例如 nuget.org。否則，就會發生錯誤。 在這個快速入門中，我們建議在 ID 中包含 Sample 或 Test ，因為發佈步驟會讓套件公開可見。 欲了解更多關於選擇 ID 的資訊，請參閱 套件識別碼的最佳實務。

4. 填寫其他想要的房產。 對於為公開使用而設計的套件，請特別注意標籤屬性，因為標籤 能 幫助他人找到你的套件並了解其功能。

   所有屬性都放在Visual Studio為專案建立的 .nuspecmanifest 裡。 有關顯示 SDK 風格專案中 Microsoft Build（MSBuild）屬性如何映射到 .nuspec 檔案屬性的表格，請參見 pack target。 關於 .nuspec 檔案屬性的描述，請參見 .nuspec 參考。

5. （可選）若要直接查看 AppLogger.csproj project 檔案中的屬性，請選擇 Project>Edit Project File。

   AppLogger.csproj 檔案會在一個新分頁開啟。

   此選項適用於使用 SDK 風格屬性的專案。

執行 pack 命令

要從你的專案建立 NuGet 套件，請依照以下步驟操作：

1. 選擇 Build>設定管理員，然後將 Active 解決方案配置 值設為 Release。

2. 在 方案總管 中，右鍵點擊 AppLogger 專案，然後選擇 Pack。

   Visual Studio 建立專案並建立 .nupkg 檔案。

3. 請查看 輸出 視窗以獲得詳細資訊，包括套件檔案的路徑。 在此範例中，已建構組件位於 bin\Release\net8.0 資料夾中，這對於 .NET 8.0 目標來說相當適用：

   1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
   1>  AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net8.0\AppLogger.dll
   1>  Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\Contoso.App.Logger.Test.1.0.0.nupkg'.
   ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
   

如果選單中缺少 Pack 指令，代表你的專案可能不是 SDK 風格的專案。 採取下列其中一個步驟：

• 升級專案，這樣你才能使用 .NET CLI。
• 請依照 的指示，使用 Visual Studio（.NET Framework， Windows） 建立並發佈套件，使用 NuGet CLI 從你的專案建立並發佈 NuGet 套件。

（可選）建置時產生套件

你可以設定 Visual Studio 在建置專案時自動產生 NuGet 套件：

1. 在 方案總管 選擇你的project，然後選擇 Project><project-name> 屬性，其中 <project-name> 是你的project名稱（AppLogger）。

2. 展開 Package 節點，選擇 General，然後選取 在建置時產生 NuGet 套件。

   

（可選）用 MSBuild 打包

除了使用 Pack 選單指令外，你也可以用這個 msbuild -t:pack 指令從專案建立 NuGet 套件。 NuGet 4.x+ 和 MSBuild 15.1+ 支援 pack 目標，只要您的專案包含必要的套件資料。

1. 當你的專案在 方案總管 中開啟時，通過選擇 工具、>、開發人員命令提示字元，開啟命令提示字元視窗。

   命令提示字元視窗會在你的專案目錄中開啟。

2. 執行下列命令：msbuild -t:pack。

欲了解更多資訊，請參閱 使用 MSBuild 建立 NuGet 套件。

發佈套件

建立 .nupkg 檔案後，請依以下步驟發布給 nuget.org。你可以使用 .NET CLI 或 NuGet CLI 來發佈。 你也會使用從 nuget.org 取得的 API 金鑰。

取得你的 API 金鑰

在發佈 NuGet 套件之前，先建立一個 API 金鑰：

1. 請登入你的 nuget.org 帳號 ，或如果你還沒有帳 號就另創 一個。

2. 在右上角選擇你的使用者名稱，然後選擇 API 金鑰。

3. 選擇 「建立」，然後輸入你的金鑰名稱。

4. 在 [選取範圍] 底下，選取 [推送]。

5. 在 「選擇套件」中，針對 Glob 圖案，請輸入星號（*）。

6. 選取 ，創建。

7. 選取 [複製] 以複製新金鑰。

   

範疇設置 提供了一種為不同目的創建獨立 API 金鑰的方法。 每個金鑰都有有效期限，你可以將金鑰鎖定特定包裹或顆粒型態。 您也可以將每個金鑰的範圍定義為特定作業：推送新套件和套件版本、僅限推送新套件版本，或將其取消列出。

透過範圍設定，您可以為管理組織套件的不同人員建立 API 金鑰，以便他們只擁有所需的權限。

欲了解更多資訊，請參閱 Scoped API 金鑰。

透過使用 .NET CLI 或 NuGet CLI 發佈

你可以使用 .NET CLI 或 NuGet CLI 將套件推送到伺服器並發佈。 到你想用的工具分頁。

dotnet nuget push <package-file> --api-key <API-key> --source https://api.nuget.org/v3/index.json

Pushing <package-file> to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
  Created https://www.nuget.org/api/v2/package/ 2891ms
Your package was pushed.

出版時的錯誤

執行指令 push 時，有時會遇到錯誤。 例如，在以下情況下你可能會收到錯誤：

• 你的 API 金鑰無效或過期了。
• 你嘗試發佈一個帶有主機上已存在識別碼的套件。
• 你對已發佈的套件做了修改，但忘記在再次發佈前更新版本號。

錯誤訊息通常會標示問題的來源。

例如，假設識別碼 Contoso.App.Logger.Test 存在於 nuget.org。如果你嘗試發佈帶有該識別碼的套件，會收到以下錯誤：

Response status code does not indicate success: 403 (The specified API key is invalid, has expired, or does not have permission to access the specified package.).

為了解決這種情況，請檢查你的 API 金鑰的範圍、有效期限和值。 若金鑰有效，錯誤表示該套件識別碼已存在於主機上。 要解決這個問題，可以把套件識別碼改為唯一，重建專案，重建 .nupkg 檔案，然後重新嘗試指令 push 。

管理已發佈的套件

當您的包裹成功發布時，您會收到一封確認電子郵件。 要查看已發佈的套件，請點到 nuget.org，在右上角選擇你的使用者名稱，然後選擇 「管理套件」。

現在你的 NuGet 套件已經在 nuget.org 發佈，其他開發者可以在他們的專案中使用它。

如果你建立了一個沒用的套件（例如這個來自空類別函式庫的範例套件），或你不希望該套件被看見，你可以將該套件 取消列出 ，以隱藏它在搜尋結果中：

1. 當套件出現在「管理套件」頁面的已發佈套件中後，選擇套件列表旁的鉛筆圖示。

   

2. 在下一頁，選擇「清單」，取消勾選「於搜尋結果中列出」勾選框，然後選擇「儲存」。

   

該套件現在會出現在「管理套件」的「未列出套件」中，並不再出現在搜尋結果中。

新增一個 readme 檔案或其他檔案

你可以在套件中加入說明文件或其他檔案。

新增一個可讀檔案

要在套件中新增 read-me 檔案，請採取以下步驟：

1. 選擇 Project>編輯Project檔案來開啟project檔案。

2. 在專案檔案中，前往 PropertyGroup 元素，然後新增一個 PackageReadmeFile 子元素：

   <Project Sdk="Microsoft.NET.Sdk">
       <PropertyGroup>
           ...
           <PackageReadmeFile>readme.md</PackageReadmeFile>
           ...
       </PropertyGroup>
   </Project>
   

3. 請前往 ItemGroup 元素，然後新增一個 None 子元素：

   <Project Sdk="Microsoft.NET.Sdk">
       <PropertyGroup>
           ...
           <PackageReadmeFile>readme.md</PackageReadmeFile>
           ...
       </PropertyGroup>
   
       <ItemGroup>
           ...
           <None Include="readme.md" Pack="true" PackagePath="\" />
           ...
       </ItemGroup>
   </Project>
   

在前述範例中，該屬性指定了一個名為 readme.md 的專案根目錄。 當你建置、打包並發佈套件後，nuget.org 會在套件頁面顯示 read-me 檔案的內容。 Visual Studio 也會在 封裝管理員 介面中顯示該檔案的內容。

例如，以下截圖展示了該 HtmlAgilityPack 套件的 read-me 檔案：

Visual Studio 封裝管理員 使用者介面截圖，顯示套件詳細資訊窗格。README 標籤描述此套件的 HTML 解析能力。

新增其他檔案

若要將其他檔案加入套件，請選擇 Project>Edit Project File 以開啟專案檔案。 接著在元素Content中加入一個ItemGroup子元素：

<ItemGroup>
  <Content Include="other-content.md">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

如需詳細資訊，請參閱《在套件中包含內容》。

相關影片

關於使用 NuGet 進行套件管理的影片，請參考 .NET Package Management with NuGet for Beginners 以及 NuGet for Beginners。

相關內容

想了解如何使用 Visual Studio .NET Framework 建立 NuGet 套件，請參見 使用 nuget.exe CLI 建立套件。

如需 NuGet 的詳細資訊，請參閱下列文章：

• 用 dotnet CLI 建立一個 NuGet 套件
• 發佈 NuGet 套件
• 建置預發布套件
• 在你的專案檔案中支援多個.NET框架
• 套件版本設定
• 建立本地化的 NuGet 套件
• .NET 應用程式升級概覽