在 SharePoint 框架上进行团队开发

项目
03/21/2023

SharePoint Framework 是用于生成 SharePoint 自定义项的全新开发模型。与目前可用的其他 SharePoint 开发模型不同，SharePoint 框架侧重于客户端开发，并基于 Gulp 和 webpack 等常用开源工具构建。此更改的一大好处是，任何平台上的开发人员都可以生成 SharePoint 自定义项。

SharePoint 框架是一个开发模型。与 SharePoint 开发者在过去使用的其他开发模型相比，尽管基本技术有所不同，但用它来生成解决方案时所采用的概念是相同的。开发者使用 SharePoint 框架工具链生成并测试解决方案。完成后，开发者会移交解决方案包，以便在 SharePoint 租户上进行部署，以供进一步测试和发布。

SharePoint Framework 包含几个不同的包。每一个包都有自己的特定版本，共同组成了发布的 SharePoint 框架。例如，2017 年 2 月的 SharePoint 框架通用版本由以下版本的 v1.0.0 包组成：

@microsoft/sp-client-base
@microsoft/sp-core-library
@microsoft/sp-webpart-base
@microsoft/sp-build-web
@microsoft/sp-module-interfaces
@microsoft/sp-webpart-workbench

对于针对 SharePoint 框架特定版本的项目，必须引用正确版本中所有不同的包。创建新项目时，SharePoint 框架 Yeoman 生成器会自动从相应版本的 SharePoint 框架添加必要的包引用。不过，将项目升级到新版 SharePoint 框架时，开发者必须特别留意是否正确更新了 SharePoint 框架包的版本号。

准备开发环境

为了构建SharePoint 框架解决方案开发人员，需要在开发计算机上使用特定的工具。与其他 SharePoint 开发模型相比，SharePoint Framework 的限制较少，允许开发者使用可最大限度地提高自己工作效率的工具，甚至允许开发者选择操作系统。

开发者可以通过几种不同的方法来配置开发环境。每种方法的优点不同，开发者团队必须深入了解这些不同方法。

SharePoint Framework 工具链

开发者必须使用一组特定的工具，才能生成 SharePoint Framework 解决方案。下面列出了每个 SharePoint Framework 开发环境都需要的一组基本工具。

Node.js

SharePoint Framework 要求在开发者计算机上安装 Node.js。 Node.js 是用于生成和打包项目的设计时工具的运行时。 Node.js全局安装在开发人员计算机上，并且有一些解决方案可用于支持并行运行多个版本的Node.js（如有必要）。

有关详细信息，请参阅设置 SharePoint 框架开发环境

NPM

npm 相当于 .NET 项目中的 NuGet，它允许开发者获取并安装包，以用于 SharePoint 框架项目。 npm 还用于安装 SharePoint 框架工具链。开发者通常使用最新版 npm，并在其计算机上进行全局安装。由于 Npm 本身就是 Node.js 包，因此如果并行运行多个版本的 Node.js，每个版本的 Node.js 都会安装自己的 npm 版本。

Gulp

Gulp 等效于 .NET 项目中的 MSBuild，负责运行生成或打包SharePoint 框架项目等任务。 Gulp 作为Node.js包分发，通常使用 npm 全局安装。

Yeoman 和 SharePoint Framework Yeoman 生成器

使用 Yeoman 和 SharePoint Framework Yeoman 生成器，开发者可以新建 SharePoint Framework 项目。 Yeoman 及其生成器以 Node.js 包的形式进行分发，通常使用 npm 以全局包的形式进行安装。全局安装的好处是，开发者可以一次性安装 Yeoman 及其生成器，并用它们来轻松创建新项目。

SharePoint Framework Yeoman 生成器与特定版本的 SharePoint Framework 相关联。使用生成器创建的项目引用特定版本的 SharePoint Framework 包，生成的 Web 部件则引用此框架的特定组成部分。 SharePoint Framework Yeoman 生成器不仅可用于创建新项目，还可用于将 Web 部件添加到现有项目中。如果全局安装它，并且必须向过去创建的现有项目添加新的 Web 部件，则新创建的 Web 部件可能与项目的其余部分不一致，甚至可能导致生成错误。可通过多种方式解决此限制，本文稍后将对此进行讨论。

TypeScript

SharePoint Framework 使用 TypeScript 帮助开发者在开发期间编写出更好的代码，并发现早已存在的错误，从而提高开发者的工作效率。 SharePoint 框架项目附带自己的 TypeScript 版本，该版本在生成过程中使用，并且不需要开发人员单独安装。

构建 SharePoint Framework 开发环境

过去，SharePoint 开发者通常使用虚拟机作为自己的开发环境。使用虚拟机，开发者可以确保要生成的解决方案可以在特定组织使用的环境中正常运行。在虚拟机中，开发者会安装并修补 SharePoint，使其达到特定组织使用的生产环境级别。在某些情况下，他们会安装其他软件，以匹配解决方案将尽可能接近运行的目标环境。使用这种方法，开发者可以尽早发现环境差异所导致的任何错误，但代价是操作复杂且需要管理不同的环境。

改为开发云解决方案并不能彻底解决这些问题。虽然开发者不再需要在开发计算机上运行 SharePoint 场，但必须考虑如何托管解决方案以及如何与 SharePoint Online 进行通信。

由于SharePoint 框架侧重于客户端开发，因此不再需要在开发计算机上安装 SharePoint。对此框架及其他包的所有依赖项均在项目中进行指定，并包含在项目文件夹中（有一些例外情况）。由于SharePoint 框架起源于云中并经常发展，因此开发人员必须确保使用与其SharePoint 框架项目相对应的工具链版本。

共享或个人开发环境

SharePoint 自定义项不仅包括直接添加到页面中的简单脚本，还包括部署为解决方案包的复杂解决方案。 SharePoint Framework 是一个开发模型，旨在成为 SharePoint 自定义项的可重复使用的结构化部署模型。生成 SharePoint Framework 解决方案时，团队中的每个开发者均使用自己的开发环境，并通过源代码管理系统与团队中的其他开发者共享项目的源代码。这样，开发人员可以同时处理同一项目并测试其解决方案，而不会影响彼此的工作效率。

过去，许多组织很难证明为 SharePoint 开发人员提供功能强大的开发计算机，在某些情况下，多个开发人员必须以生产力为代价共享同一台计算机。借助 SharePoint 框架，开发人员可以使用市场标准的开发人员计算机来生成 SharePoint 自定义项。

在主机上开发

为SharePoint 框架项目设置开发环境的最简单选择可能是直接在主机上安装所有工具。如果你的团队只要处理 SharePoint Framework 项目，可以在计算机上安装 Node.js。如果他们处理其他Node.js项目，则可以使用第三方解决方案（如 nvm ）并行运行多个版本的Node.js。

在安装 SharePoint 框架工具链所需的工具后，开发者将安装 Yeoman 和 SharePoint 框架 Yeoman 生成器。这两种工具通常进行全局安装。然而，鉴于 SharePoint 框架 Yeoman 生成器与特定版本的 SharePoint 框架相关联，并且开发者可能需要处理使用不同版本创建的项目，因此开发者不得不卸载生成器，然后安装与当前处理的特定项目对应的生成器版本。更为切实可行的方法是，在给定项目中对 Yeoman 进行全局安装，但对 SharePoint 框架 Yeoman 生成器进行本地安装。尽管这样做会产生一些开销，但却可以帮助开发者确保在今后需要向项目添加新元素时，与项目的其余组成部分保持兼容。

在主机上进行开发的一个好处是，开发人员只需按自己的偏好配置一次计算机，即可在所有项目中使用它。此外，当软件在主机上执行时，它可以直接访问 CPU、内存和磁盘 I/O，而无需在两者之间使用虚拟化层，这与运行虚拟化的同一软件相比，性能更佳。

在虚拟机中开发

过去，SharePoint 开发人员最常见的方法是使用虚拟机作为生成 SharePoint 解决方案的主要开发环境。使用虚拟机，开发者可以满足各个项目的不同要求。

在 SharePoint Framework 上生成解决方案时，组织可以获得与过去生成 SharePoint 解决方案时一样的好处。使用虚拟机，他们可以将开发软件与主机操作系统隔离开来，这是一个常见要求，尤其是在大型组织中。通过为每个项目开发人员创建单独的虚拟机，可以确保他们使用的工具链与项目兼容，即使将来需要选取特定项目也是如此。

使用虚拟机并非没有缺点。虚拟机很大，需要开发人员使用足够强大的计算机，以可接受的性能运行它们，才能提高工作效率。此外，特别是在较长时间内，开发人员必须使操作系统保持最新状态，并确保运行所有必要的安全更新。当开发人员在虚拟机中工作时，他们要么不得不在新项目开始时花一些时间来根据自己的偏好配置标准虚拟机，要么必须屈从于标准设置，但代价是他们的工作效率。由于虚拟机运行包含其所有组件的完整操作系统，因此要确保团队中所有开发人员使用的所有虚拟机保持一致要困难得多。与其他类型的开发环境相比，使用虚拟机生成 SharePoint Framework 解决方案非常昂贵，不论是从成本角度，还是从时间角度来看。

使用 Docker 进行开发

在主机上开发与在虚拟机中开发的折中方法是使用 Docker。 Docker 是一种类似于虚拟机的软件虚拟化技术，但存在一些差异。与虚拟机相比，使用 Docker 映像最重要的好处是，Docker 映像更易于创建、维护和分发，与虚拟机) 所需的数十 GB 磁盘空间相比，Docker 映像更轻量级 (几百 MB，并且开发人员可以使用已在主机上安装和配置的工具和首选项。

与虚拟机类似，Docker 容器运行的是操作系统的虚拟化实例（最常基于 Linux）。用于创建容器的映像中安装的所有软件在容器内独立运行，只能访问与容器显式共享的主机文件系统部分。由于在容器关闭后对 Docker 容器内文件系统的所有更改都会遭放弃，因此开发者从其主机共享文件夹来存储源代码。

有关详细信息，请参阅使用 Docker 生成 SharePoint 框架解决方案。

SharePoint Framework 项目中的开发工作流

SharePoint 框架基于开源工具链，并遵循在同一堆栈上构建的其他项目中存在的常规开发工作流。下面介绍了典型 SharePoint Framework 项目中的工作流。

新建 SharePoint 框架项目

使用 SharePoint Framework 生成 SharePoint 自定义项时，首先要新建 SharePoint Framework 项目。为此，请使用 SharePoint Framework Yeoman 生成器。生成器会提示你回答几个与项目名称或其位置相关的问题。此外，还可以使用生成器创建首个 Web 部件或扩展。尽管可以自由地为每个组件选择不同的 JavaScript 框架，但一般建议是每个 SharePoint 框架项目使用一个框架。

锁定依赖项版本

SharePoint 框架 Yeoman 生成器搭建的新SharePoint 框架项目依赖于SharePoint 框架包和其他包才能正常运行。生成 Web 部件时，可能需要包含其他依赖项，例如Angular或 jQuery。在 SharePoint Framework 项目中，依赖项是使用 npm 进行安装。每个依赖项都是一个特定版本的 Node.js 包。默认情况下，依赖项使用版本范围进行引用，旨在帮助开发人员更轻松地使其依赖项保持最新状态。此方法的结果是，在两个时间点还原同一项目的依赖项可能会产生不同的结果，这甚至可能导致项目中断。

在使用开放源代码工具链生成的项目中，为了规避项目期间的依赖项更改带来的风险，常见解决方法是锁定所有依赖项的版本。在项目中添加依赖项时，开发者可以选择安装特定版本的依赖项，而不是具有版本范围的依赖项，具体方法是使用 --save-exact 参数调用 npm install 命令。

不过，这并不影响特定包的子依赖项。要有效锁定项目中所有依赖项及其子依赖项的版本，开发者可以使用 NPM 支持的本机锁定文件功能。有关详细信息，请参阅 npm-package-locks：NPM 锁定文件的说明。

将项目添加到源代码管理系统

为了让团队中的其余成员能够处理同一项目，请将项目添加到团队在使用的源代码管理系统中。具体步骤因团队使用的系统而异。

SharePoint 框架项目是使用 .gitignore 文件创建的，该文件描述了应从源代码管理系统中排除哪些文件。如果团队使用的是源代码管理系统，而不是 Git（如带 Team Foundation System 存储库的 Visual Studio Team System），应确保在源代码管理系统中添加项目的正确文件。此外，在生成过程中排除依赖项和自动生成文件，可以确保团队高效工作。

开发者应特别注意一点，就是不要在源代码管理系统中添加 node_modules 文件夹。此文件夹包含项目依赖的包，以及在使用 npm install 命令还原依赖项时自动安装的包。一些包编译成二进制文件，编译过程因操作系统而异。如果团队使用不同的操作系统，则在源代码管理中包含 node_modules 文件夹可能会中断某些团队成员的生成。

从源代码管理系统获取项目

第一次从源代码管理系统中获取项目时，获取的是项目的源代码，不会获得生成项目所需的任何 SharePoint 框架库。与处理 .NET 项目和使用 NuGet 包类似，必须先还原依赖项。在 SharePoint 框架项目中，可以通过在命令行中执行 npm install 完成此操作，与其他所有在 Node.js 基础之上生成的项目类似。 NPM 将结合使用 package.json 文件和 package-lock.json 文件中的信息，然后安装所有包。

注意

通常情况下，必须有 Internet 连接，才能使用 npm install 命令还原依赖项，因为包是从 https://registry.npmjs.org 中下载的。

如果遇到网络连接问题或 NPMJS 注册表不可用，则生成失败。有多种方法可以缓解此限制造成的影响。其中一种方法是使用 shrinkpack 下载所有依赖项的 tarball，然后将它们存储在源代码管理系统中。 Shrinkpack 自动将 npm-shrinkwrap.json 文件更新为使用本地 tarball，同时允许脱机安装项目的依赖项。

一些包在安装过程中编译成二进制文件。此编译过程因体系结构和操作系统而异。如果在运行 Linux 的 Docker 容器中还原依赖项，然后尝试在 Windows 主机上生成项目，则会看到错误消息，指出用于生成和运行二进制文件的环境类型不一致。

在团队开发解决方案期间，可能会向项目中添加新的或更新后的依赖项。如果自上次从源代码管理系统获取项目后 package.json 文件发生了变化，必须在命令行中运行 npm install，以安装缺少的依赖项。如果不确定 package.json 文件是否有变化，为了保险起见，可以在命令行中运行 npm install，以确保依赖项是最新的，但又不会对项目有任何损坏。

将包添加到项目

使用现有包来完成特定任务可提高工作效率。 https://www.npmjs.com 是可以在项目中使用的包的公共注册表。

重要

因为在将包发布到 https://www.npmjs.com 之前没有任何正式的验证过程，所以应从内容和许可证的角度出发，仔细检查能否使用特定包。

若要将包添加到SharePoint 框架请在命令行中执行 npm install {package} --save 或 npm install {package} --save-dev 命令，例如：npm install angular --save。使用 --save 或 --save-dev 参数可确保将包添加到 package.json 文件，并且团队中的其他开发者在还原依赖项时也会获得此包。否则，在不是自己的计算机上生成项目将会失败。添加解决方案在运行时（如 Angular 或 jQuery）需要的包时，应使用 --save 参数。应使用 --save-dev 参数安装生成过程（如其他 Gulp 任务）中需要的包。

安装包时，如果没有指定版本，npm 会安装包注册表（默认情况下为 https://www.npmjs.com）中的最新版本，通常是要使用的版本。必须指定包版本的情形是，使用的是 npm shrinkwrap.json，且要将现有包升级到新版本。默认情况下，npm 会安装 npm shrinkwrap.json 文件中列出的版本。在 npm install 命令中指定版本号（如 npm install angular@1.5.9 --save）将安装相应的包，并更新 npm-shrinkwrap.json 文件中的版本号。

使用内部包

由于团队开发的是客户端解决方案，因此可能会生成要在所有项目中重复使用的通用代码库。在许多情况下，除了部署到生产环境的捆绑包之外，此类库还包含未与组织外部公开共享的专有代码。处理 SharePoint Framework 项目时，团队可以通过多种方法利用项目中的内部库。

托管专用包注册表

过去，许多生成 .NET 解决方案的组织托管专用 NuGet 存储库，以利用 NuGet 包管理系统来管理内部包。由于 SharePoint Framework 使用 npm 进行包管理，因此组织同样可以使用专用注册表来管理内部包。内部开发的包会发布到专用注册表，以供组织内的所有项目使用。

使用专用包注册表时，组织可以在云中托管的不同产品/服务之间进行选择，也可以在自己的基础结构上托管自己的注册表。

使用专用包注册表，组织可以集中管理跨不同项目使用的通用代码。通过制定有关如何更改共享代码库的独立治理计划，组织可以确保代码库不仅非常优质，还能按预期让所有开发者获益，而不是成为拖慢项目进度的负担。

使用 Visual Studio Team Services 或 Team Foundation Server，组织可以很方便地直接在 VSTS/TFS 中创建专用 npm 注册表。使用其他源代码管理系统的组织可以使用其他解决方案托管其程序包。在云中托管的常见专用注册表是 npm 企业。有意自行托管注册表的组织可以从许多开放源代码实现（如 Sinopia 或其分叉 Verdaccio 或 Nexus）中进行选择。

注意

用于托管专用包注册表的不同引擎处于不同的开发阶段，应从功能、许可证和支持的角度出发，仔细评估特定引擎是否满足你的需求。

为简化专用包注册表的安装和管理，大多数引擎都提供随时可用的 Docker 映像。

使用 NPM 链接的链接包

除了使用专用注册表之外，还可以使用链接包。虽然不用设置注册表，但需要在所有开发者计算机和生成服务器上进行仔细协调。

首先，团队中的每个开发者都必须在其开发计算机上复制共享包。在命令行中，开发者需要将工作目录更改为一个共享包，然后必须执行 npm link 命令。此命令将特定包注册为特定开发计算机上的全局包。接下来，开发者必须将工作目录更改为要在其中使用共享包的项目目录。然后，他们通过执行命令行中的 npm install {shared_package} --save 命令，以安装任何其他包的方式安装包。由于共享包进行的是全局安装，因此 npm 会将该版本作为包的安装源。此时，从项目的角度来看，此包已像其他所有公共包一样安装起来，开发者可以选择如何将包与项目相关联。

必须在所有开发计算机和生成服务器上链接包。如果未使用 npm link 命令链接共享包，将无法还原项目依赖项，并导致生成中断。

同时开发共享包和项目时，引用链接包在项目早期非常有用。有了链接包之后，不用为了在项目中使用最新代码，而将包的新版本发布到注册表中。请务必留意以下风险：如果开发者引用他们在本地更改的共享库版本，并且尚未将其提交到源代码管理系统中，则会损坏团队中其余开发者生成的内容。

结合使用专用包注册表和链接包

可以结合使用专用包注册表和链接包。例如，可以采用开发人员引用链接包，生成服务器从专用注册表拉取共享库的方式工作。从项目的角度来看没有任何变化：package.json 文件中的包引用可以同时从链接包和专用注册表进行解析。团队唯一需要注意的一点是，在执行生成之前，将对共享库的最新更改发布到专用注册表中。

随着共享库代码逐渐稳定，并且为了满足特定项目的需求而需要执行的更改越来越少，开发者更有可能只是从专用注册表引用已发布的包，而不用进行更改。

确保代码一致性和质量

软件开发团队通常都在竭力维护项目的一致性和高质量。不同的开发者有不同的编码风格和偏好。每个团队中都有技能娴熟的开发者，也有在特定领域缺乏经验的开发者。此外，许多组织或行业都有软件必须符合的特定法规。所有这些挑战都会使开发者很难掌握进度。特别是，当截止时间临近时，开发者往往会快速完成项目，但代价是质量下降。从长远来看，这样做比没有按时完成更具危害性。

为团队选择 JavaScript 库并遵循编码标准

如果团队过去一直在生成 SharePoint 自定义项，可能会有规定如何生成自定义项以及在项目中使用哪些工具和库的编码标准。遵循编码标准，各个开发者就不会按照个人偏好编写代码，这样一来团队的其他成员就更加容易接手了。此外，编码标准反映了团队多年来累积的经验，可以提高自定义项的生成效率和质量。

与目前可用的其他 SharePoint 自定义项模型不同，SharePoint Framework 侧重于客户端开发。尽管没有严格要求，但 SharePoint Framework 建议使用 TypeScript 帮助开发者在开发过程中编写出更好的代码，并发现早已存在的所有不一致问题。可用于完成相同任务的客户端库还有数百个。如果团队在过去已完成过客户端开发，那么可能已对特定库有所偏好。如果没有，调查几个最常见的库，并为团队或（最好是）整个组织选择一个库，将会大有裨益。

在所有项目中使用相同的库，可以更加轻松地培训新的团队成员，并能在项目之间交换团队成员。随着客户端开发经验不断累积，组织将能够在所有项目中受益。此外，在整个组织中使项目标准化还能缩短交付时间，并降低项目的维护成本。新库每天都会在 Internet 上发布，如果不断切换使用最新的库，则会发现自己工作效率低下，同时交付的解决方案质量也很差。

使组织内使用的库标准化还有助于提升解决方案的性能。由于整个组织使用的是同一个库，因此用户只需要下载一次，这将大大加快解决方案的加载时间，从而改善用户体验。

选择一个最常见的库，可重复利用其他开发者在长时间使用该库的过程中累积的知识和经验，而且其他开发者已解决了你可能会遇到的许多问题。对于最常见的库，也有团队可遵循的编码标准。通过遵循特定库的现有市场标准，可以雇佣开发者并帮助他们提高工作效率，从而让组织轻松扩大团队规模。

例如，为了在 SharePoint Framework 上生成第一方解决方案，Microsoft 选择了 React。此外，Microsoft 中的其他许多团队（如 OneDrive 或 Delve）也在项目中使用 React。这并不意味着也应该在所有 SharePoint Framework 项目中使用 React，而是说选择适用于组织的客户端库至关重要。例如，如果团队已有 Angular 或 Knockout 经验，没有理由不从这一经验中获益并在生成 SharePoint 框架解决方案时保持工作效率。

在解决方案的整个生命周期强制实施编码标准和策略

虽然遵循编码标准的优势明显，但只有编码标准并不意味着能在 SharePoint 自定义项的整个开发和测试过程中积极贯彻这些标准。开发者等待的时间越长，团队验证解决方案是否符合团队的编码标准和组织策略越困难，修复项目中发现的任何缺陷也就成本越高。下面介绍了团队应在开发过程中遵循的几项做法，以强制执行 SharePoint 解决方案的治理计划。

Lint

Lint 是验证代码是否符合特定规则的过程。默认情况下，SharePoint Framework 项目使用 TypeScript 生成。在生成的每个项目中，TSLint（适用于 TypeScript 的 Linter）根据预定义的一组规则分析项目，并报告发现的任何不一致问题。开发者可以选择要启用的规则，也可以生成自己的规则，以反映团队或组织的准则（如有必要）。

开发者可以使用 Lint 来验证 TypeScript 文件的内容（但不仅限于此）。 CSS、JavaScript 或 Markdown 等最常见的语言都有适用的 Linter，如果团队有针对这些语言的具体准则，那么在 linter 中实现它们将非常有利，这样每当开发者生成项目，都可以自动对其进行验证。

自动测试

使用自动测试，开发者可以很容易地验证在将最新更改应用到项目后，所有元素是否继续按预期运行。随着项目的发展，自动测试的重要性也在增强：随着代码库的规模扩大，每项更改对代码的其他一些部分造成的影响力和风险也在加大。借助自动测试，开发者可以验证解决方案能否正常运行，并尽早发现所有可能出现的问题。

SharePoint 框架为 Karma 测试运行程序和 Mocha 框架（开发者可以用来编写测试）提供标准支持。如有必要，开发者可以使用 SharePoint 框架随附的附加构造基块（如 Jest 和 PhantomJS），进一步扩大测试的覆盖面。 SharePoint 框架项目中的所有测试都可以使用标准 gulp test 任务运行。

代码分析

如果 Lint 有助于验证特定文件的语法，开发者通常需要获得更多支持才能验证整个项目是否符合准则。一般情况下，Linter 侧重于验证代码本身，但会忽略特定代码文件表示的上下文。 SharePoint Framework 解决方案中的项有具体要求。例如，项目中的 Web 部件应有唯一 ID。另外，组织也可能有其他要求，如不从 CDN 引用脚本，或只使用某个库的特定版本。在这种情况下，Linter 通常无法满足需求，开发者需要使用其他工具。

SharePoint 代码分析框架 (SPCAF) 是第三方解决方案，拥有质量保证和安全角色的 SharePoint 开发者、管理员和员工通常用它来验证 SharePoint 自定义项是否符合组织的质量准则。 SPCAF 与整个应用程序生命周期进程相集成，帮助组织降低 SharePoint 自定义项所有权的总成本。 SPCAF 提供了一套专门针对 SharePoint Framework 解决方案的规则。

升级 SharePoint 框架项目

将 SharePoint 自定义项部署到生产环境通常并不意味着生命周期的结束。要求不断变化或新要求层出不穷，这两种情况都会导致对解决方案进行更改。为了正确更新之前部署到生产环境的自定义项，开发者必须注意许多方面。

语义版本控制 (SemVer)

SharePoint Framework 使用语义版本控制 (SemVer) 跟踪版本号（有一些例外情况）。语义版本控制是全球软件开发者广泛采用的版本控制模式。 SemVer 号包含三个数字 (MAJOR.MINOR.PATCH) 和一个可选标签。例如，1.0.1。

注意

目前，SharePoint 框架仅支持使用不带标签的三个数字。

SemVer 号的不同部分会进行提升，具体视应用于解决方案的更改的类型而异：

如果所做的更改向后不兼容，则为 MAJOR
如果所做的更改中引入向后兼容的新功能，则为 MINOR
如果所做的更改为向后兼容的 bug 修复，则为 PATCH

请务必注意，SemVer 只是一个协定。完全由团队来决定是否遵循此协定，从而明确最新版本中的更改。

若要详细了解语义版本控制，请访问 http://semver.org。

提升版本号

在更新部分 SharePoint Framework 解决方案时，开发者应提升受影响部分的版本号，以明确指出更改了哪些元素以及这些更改造成的影响。

提升 package.json 中的包版本

SharePoint Framework 包的结构类似于 Node.js 包。依赖项和元数据存储在项目文件夹中的 package.json 文件内。 package.json 文件中的一个属性是表示整个项目版本的版本属性。默认情况下，当前解决方案中的所有组件都会继承此版本号作为其版本。每次按照 SemVer 约定规划项目的新版本时，开发者都应提升 package.json 文件中的版本号。

提升 package-solution.json 中的解决方案包版本

SharePoint 框架解决方案是使用安装在 SharePoint 租户上的应用程序目录中的 *.sppkg 文件部署的。 *.sppkg 文件类似于 SharePoint 外接程序包，并遵循相同的版本控制约定。 当前版本的 *.sppkg 包是使用由四个部分构成 (MAJOR 定义的。小。修订。BUILD) config/package-solution.json 文件中存储的编号。为明确起见，开发者应让此编号与 package.json 文件中的版本号保持同步，因为这两个编号都是指整个项目的版本。

注意

必须在版本轮替时在 package-solution.json 文件中提升版本号，才能在 SharePoint 中正确部署包的新版本。

更新依赖项

更新 SharePoint 框架项目的原因之一可能是其中一个基础依赖项有所变化。例如，新版 Angular 修复了 bug 并提升了性能。如果你的团队遵循使用 npm shrinkwrap 锁定依赖项版本的建议方法，则你可以使用 npm install {package}@{version} --save 命令将依赖项更新到特定版本，并测试项目，以验证它是否按预期与最新更新一起工作。总体项目更新可能从修补程序到完整的主要版本无所不包，具体视基础依赖项的更改对项目造成的影响而异。

重要

请勿手动修改 package.json 文件中的依赖项的版本号。如果使用锁文件（如 npm shrinkwrap），则将忽略对 package.json 文件的手动更改，并且将改用锁文件中记录的版本号，这将导致难以跟踪项目中的错误。

注意项目结构变化

将项目更新到较新版本的 SharePoint 框架可能需要更改项目结构和项目配置文件。在更新项目依赖项中的 SharePoint 框架版本之前，应始终使用要升级到的 SharePoint 框架版本创建新项目，并仔细将其结构和内容与现有项目进行比较。这将使你可以确定升级对项目的影响，并有助于避免对项目进行重大更改。

谨慎使用 npm outdated

找出项目中哪些依赖项需要更新的方法之一是运行 npm outdated 命令。此命令会扫描你的依赖关系树，并会显示哪些程序包可以更新。虽然使用此命令很方便，但要小心谨慎。

从 SPFx v1.3 开始，SharePoint 框架 Yeoman 生成器允许选择是否要为仅适用于 SharePoint Online，或者仅适用于 SharePoint 2016 功能包 2 及更高版本和 SharePoint Online 的项目搭建基架。托管于本地的 SharePoint 使用 SharePoint 框架的旧版本，而不是 SharePoint Online 中提供的最新版本。如果要在与本地 SharePoint 兼容的项目上运行 npm outdated 命令，则建议将所有核心 SharePoint 框架包更新为发布到 npm 的最新版本。遗憾的是，将这些程序包更新到最新版本后，项目将不再适用于本地 SharePoint。在更新 SharePoint 框架程序包的版本之前，你应该始终验证项目是否适用于本地托管的 SharePoint，如果是，那么必须支持哪个版本的 SharePoint 框架。

在发布模式下生成和打包项目

验证解决方案能按预期运行后，使用 gulp bundle --ship 命令在发布模式下生成项目。然后使用 gulp package-solution --ship 命令创建一个新包。无需先运行 gulp bundle --ship 命令，包就会包括旧版项目。

部署解决方案的新版本

生成和打包完项目后，下一步是进行部署。首先，部署位于项目的 ./temp/deploy 文件夹中的已更新 Web 部件捆绑包。在旧版解决方案的 Web 部件捆绑包旁边发布文件。

注意

只要有活跃的 Web 部件实例在使用旧版解决方案，就不得进行删除。捆绑包文件的每个版本都有一个唯一名称，在更新 Web 部件之前删除旧版会损坏这些 Web 部件。

接下来，将新的解决方案包部署到 SharePoint 应用程序目录。有必要通知 SharePoint 应该应用解决方案的新版本。

通过