写C#代码久了，总会积累一些好用的工具类：字符串处理、加密解密、日志封装等等。每次新开项目都复制一遍源码，不仅麻烦，而且一旦修了Bug还得挨个项目去改。最优雅的解决方案就是把这些代码封装成类库，打包成NuGet包，之后任何项目一条命令就能引用，升级也只需要更新版本号。本文将从零开始，带你完成第一个NuGet包的创建、本地测试和正式发布。
一、创建类库项目并配置包信息
首先打开Visual Studio，新建项目时选择类库模板，框架建议选择.NET 6或.NET 8这类长期支持版本。也可以直接用命令行创建：
dotnet new classlib -n MyUtils -o MyUtils cd MyUtils
项目创建好后，关键的一步是配置包的元数据。右键项目文件选择编辑，或者直接打开MyUtils.csproj，填入以下内容：
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<PackageId>MyUtils</PackageId>
<Version>1.0.0</Version>
<Authors>你的名字</Authors>
<Company>你的公司</Company>
<Description>一套常用的C#工具类库，包含字符串处理和加密功能</Description>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<RepositoryUrl>https://github.com/yourname/MyUtils</RepositoryUrl>
<PackageIcon>icon.png</PackageIcon>
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
</PropertyGroup>
<ItemGroup>
<None Include="icon.png" Pack="true" PackagePath="" />
</ItemGroup>
</Project>
这些属性会直接展示在NuGet管理器和nuget.org的包详情页上，其中Description写清楚包能做什么非常关键，直接影响别人是否愿意安装。如果打算发布到公共源，建议准备一张128x128的图标图片放在项目根目录。另外，版本号建议遵循SemVer语义化版本规则：重大不兼容修改升主版本，新增功能升次版本，修Bug升修订号，例如1.2.3。
二、打包并本地测试
配置完成后执行打包命令，生成的.nupkg文件就是最终的NuGet包，位于项目的bin\Debug目录下：
dotnet pack --configuration Release
发布前务必先在本地测试一遍，否则包里缺文件或者API设计不合理，发布出去再撤回就很尴尬。本地测试有两种常用方式。第一种是搭建本地文件夹源：新建一个空文件夹比如C:\LocalNuGet，在Visual Studio的NuGet包管理器设置中把这个文件夹添加为程序包源，然后把生成的nupkg文件复制进去，其他项目就能搜索安装了。
第二种方式更直接，在测试项目里通过路径引用：
<ItemGroup> <PackageReference Include="MyUtils" Version="1.0.0" /> </ItemGroup>
测试时重点确认三件事：引用后能否正常编译、公开的类和方法是否都能访问到、依赖的其他第三方包有没有被正确带进依赖链。如果类库里某些方法不想暴露出去，记得用internal修饰，或者结合InternalsVisibleTo控制可见范围。
三、发布到nuget.org与日常更新
公共发布需要先到nuget.org注册账号并获取API Key。登录后进入账户设置里的API Keys页面，点击创建，作用域选择Push新包和更新包，过期时间按需设置，生成后立即复制保存，这个Key只显示一次。
拿到Key之后执行推送命令：
dotnet nuget push bin\Release\MyUtils.1.0.0.nupkg ^ --api-key 你的APIKey ^ --source https://api.nuget.org/v3/index.json
推送成功后，包会先进入处理状态，几分钟内就能在nuget.org搜索到。注意nuget.org有一个重要规则：已发布的版本号永久不可覆盖，即使马上删除包，该版本号也不能再次使用。所以每次更新代码必须修改csproj里的Version再重新打包推送。日常更新推荐一条命令完成打包加推送：
dotnet pack --configuration Release && dotnet nuget push bin\Release\MyUtils.1.0.1.nupkg --api-key 你的APIKey --source https://api.nuget.org/v3/index.json
如果是企业内部使用，不想把代码公开到公网，可以搭建私有源。最简单的方案是搭建BaGet或ProGet服务，或者直接用Azure Artifacts、团队局域网共享文件夹作为源。私有源的推送命令完全一样，只需要把--source参数换成私有源地址即可。
四、常见问题与避坑建议
新手第一次发布最容易遇到几个问题。第一，包推送时报409冲突，说明版本号已存在，改高版本号重新打包即可。第二，目标框架选择问题：如果包只在.NET 8项目里用，TargetFramework写net8.0没问题，但想兼容.NET Framework的老项目，就需要改成多目标并使用netstandard2.0：
<TargetFrameworks>netstandard2.0;net8.0</TargetFrameworks>
第三，符号文件的问题。默认打包不会包含PDB调试符号，使用方调试时看不到源码。可以在csproj中加上<IncludeSymbols>true</IncludeSymbols>和<SymbolPackageFormat>snupkg</SymbolPackageFormat>，打包时会额外生成一个snupkg文件，推送时一并上传即可。
最后给一个实用建议：发布第一个包之前，先用dotnet nuget locals http-cache --clear清理本地缓存，避免测试时一直引用到旧版本造成误判。另外记得把源码推送到GitHub并在csproj里配置RepositoryUrl，这样nuget.org页面会自动关联仓库链接，可信度也会更高。掌握这套流程后，无论是个人工具库还是公司基础组件，都可以标准化地分发和升级了。
NuGet包发布C#类库Visual Studio修改时间：2026-09-07 09:14:39