.nuspec 是 nuget 包的 xml 清单文件，定义元数据（如 id、version、authors）和依赖关系，不参与编译，仅用于打包；需正确声明命名空间，避免非法字符与配置冲突。
什么是 .nuspec 文件
.nuspec 是一个 XML 格式的清单文件，用于定义 NuGet 包的元数据和内容结构。它不参与编译，只在打包（nuget pack 或 dotnet pack）时被读取，告诉 NuGet “这个包叫什么、作者是谁、依赖哪些包、包含哪些文件”。它相当于 NuGet 包的“身份证+说明书”。
如何用 XML 定义基本元数据
核心元素必须放在 <package></package> 根节点下，最简可用结构包含 <metadata></metadata> 和可选的 <files></files>。常见字段有：
-
<id></id>：包唯一标识符，通常与项目名一致，不能含空格或特殊字符 -
<version></version>：语义化版本号，如1.2.3或带预发布标签的2.0.0-beta1 -
<title></title>：显示在 NuGet.org 上的名称（可选，不强制等于<id></id>） -
<authors></authors>：逗号分隔的作者名，如<authors>Alice,Bob</authors> -
<description></description>：简短说明，会出现在包管理器 UI 中 -
<projecturl></projecturl>、<license type="expression"></license>、<repository></repository>：现代推荐填写的开源信息字段
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">
<metadata>
<id>MyLibrary</id>
<version>1.0.0</version>
<title>My Awesome Library</title>
<authors>DevTeam</authors>
<description>A small utility library for common tasks.</description>
<projectUrl>https://github.com/example/mylibrary</projectUrl>
<license type="expression">MIT</license>
<repository type="git" url="https://github.com/example/mylibrary.git" />
</metadata>
</package>添加依赖和程序集引用
依赖关系写在 <dependencies></dependencies> 下，每个 <dependency></dependency> 指定目标框架（targetFramework 属性）和版本范围。注意：targetFramework 值必须是 NuGet 框架简称（如 net6.0、netstandard2.0），不是完整 TFM（如 net6.0-windows 可能被忽略）。
- 不指定
targetFramework→ 默认适用于所有框架 - 版本范围支持
[1.0.0,2.0.0)（含 1.0.0，不含 2.0.0）、1.0.0（精确匹配）、1.0.*（通配，仅限主版本） - 若项目使用 SDK 风格（
<project sdk="Microsoft.NET.Sdk"></project>），通常无需手动维护<files></files>，dotnet pack会自动包含输出程序集
<metadata>
<!-- ... 其他字段 -->
<dependencies>
<group targetFramework="net6.0">
<dependency id="Newtonsoft.Json" version="[13.0.3,14.0.0)" />
<dependency id="Microsoft.Extensions.Logging" version="7.0.0" />
</group>
<group targetFramework="netstandard2.0">
<dependency id="Newtonsoft.Json" version="12.0.3" />
</group>
</dependencies>
</metadata>常见错误和兼容性注意点
很多构建失败或包行为异常，根源在于 .nuspec 的细节偏差：
- XML 命名空间（
xmlns）缺失或拼错 →nuget pack报错 “The element 'package' in namespace … has invalid child element” -
<id></id>含非法字符（如下划线开头、中文、点号过多）→ NuGet.org 拒绝上传，本地安装也可能失败 - 混合使用
<files></files>和 SDK 打包 → 若<files></files>指向未生成的 DLL 路径，打包会静默跳过该文件，但不报错 - 未声明
<repository></repository>却在 GitHub 发布 → NuGet.org 无法自动关联源码链接，影响可信度 - 用
<license type="file"></license>但未在<files></files>中包含对应 LICENSE 文件 → 用户无法在本地查看许可证
如果只是为 .NET SDK 项目生成包，优先用 dotnet pack + .csproj 内置属性（如 <packageid></packageid>、<version></version>），而非单独维护 .nuspec —— 除非你需要精细控制文件映射或跨框架依赖分组。
