设置 SharePoint 框架开发环境Set up your SharePoint Framework development environment

可以使用 Visual Studio 或自己的自定义开发环境生成 SharePoint 框架解决方案。You can use Visual Studio or your own custom development environment to build SharePoint Framework solutions. 可以使用 Mac、PC 或 Linux。You can use a Mac, PC, or Linux.

备注

请务必先设置 Office 365 租户,再执行本文中的步骤。Before following the steps in this article, be sure to Set up your Office 365 tenant.

也可以观看 SharePoint PnP YouTube 频道上的这段视频,按照下面这些步骤操作:You can also follow these steps by watching this video on the SharePoint PnP YouTube Channel:

安装开发人员工具Install developer tools

安装 NodeJSInstall NodeJS

安装 NodeJS LTS 版本 10Install NodeJS LTS version 10.

  • 如果使用的是 Windows,可以使用此链接中的 msi 安装程序,以最简便的方式设置 NodeJS。If you are in Windows, you can use the msi installers in this link for the easiest way to set up NodeJS.
  • 如果已安装 NodeJS,请务必使用 node -v 检查最新版本。If you have NodeJS already installed, check that you have the latest version by using node -v. 它应返回最新的 LTS 版本It should return the current LTS version.

重要

SharePoint 框架当前支持的 NodeJS LTS 版本包括 Node.js v8.xNode.js v10.xThe current supported LTS version of NodeJS for the SharePoint Framework is both 8.x and 10.x. 请注意,SharePoint 框架开发当前不支持 9.x 和 11.x 版本。Notice that 9.x or 11.x versions are currently not supported with SharePoint Framework development.

备注

如果要生成用于 SharePoint Server 2016 的 SharePoint 框架组件,请参阅 SPFx 和 SharePoint Server 2016 部分中的其他详细信息,了解应安装的 NodeJS 版本的其他详细信息。If you are building SharePoint Framework components for SharePoint Server 2016, refer to additional details in the SPFx & SharePoint Server 2016 section for additional details on which version of NodeJS you should install.

安装代码编辑器Install a code editor

若要生成 Web 部件,可以使用任何支持客户端开发的代码编辑器或 IDE,如:You can use any code editor or IDE that supports client-side development to build your web part, such as:

此文档中的步骤和示例使用 Visual Studio Code,但你可以使用你选择的任何编辑器。The steps and examples in this documentation use Visual Studio Code, but you can use any editor of your choice.

安装 Yeoman 和 gulpInstall Yeoman and gulp

Yeoman 可帮助启动新项目,并规定最佳做法和工具,以帮助你保持高效率。Yeoman helps you kick-start new projects, and prescribes best practices and tools to help you stay productive. SharePoint 客户端开发工具包括用于新建 Web 部件的 Yeoman 生成器。SharePoint client-side development tools include a Yeoman generator for creating new web parts. 此生成器提供常见生成工具、常见样本代码,以及托管主机 Web 部件以供测试的常见样本网站。The generator provides common build tools, common boilerplate code, and a common playground website to host web parts for testing.

输入以下命令,安装 Yeoman 和 gulp:Enter the following command to install Yeoman and gulp:

npm install -g yo gulp

安装 Yeoman SharePoint 生成器Install Yeoman SharePoint generator

Yeoman SharePoint Web 部件生成器帮助你快速创建一个具有适当工具链和项目结构的 SharePoint 客户端解决方案项目。The Yeoman SharePoint web part generator helps you quickly create a SharePoint client-side solution project with the right toolchain and project structure.

若要全局安装 SharePoint 框架 Yeoman 生成器,请输入以下命令:To install the SharePoint Framework Yeoman generator globally, enter the following command:

npm install -g @microsoft/generator-sharepoint

若要详细了解 Yeoman SharePoint 生成器,请参阅使用 Yeoman SharePoint 生成器搭建项目基架For more information about the Yeoman SharePoint generator, see Scaffold projects by using Yeoman SharePoint generator.

信任自签名开发人员证书Trusting the self-signed developer certificate

在开发环境中测试自定义解决方案时使用的 SharePoint 框架本地 WebServer 默认使用 HTTPS。The SharePoint Framework's local webserver, used when testing your custom solutions from your development environment, uses HTTPS by default. 这是使用开发自签名 SSL 证书实现的。This is implemented using a development self-signed SSL certificate. 自签名 SSL 证书不受开发人员环境信任。Self-signed SSL certificates are not trusted by your developer environment. 必须先将开发环境配置为信任此证书。You must first configure your development environment to trust the certificate.

实用工具任务以 Gulp 任务的形式包含在每个 SharePoint 框架项目中。A utility task is included in every SharePoint Framework project in the form of a gulp task. 可以选择立即这样做,也可以等到创建首个项目后再这样做,如生成首个 SharePoint 客户端 Web 部件(Hello World 第 1 部分):预览 Web 部件教程中所述。You can elect to do this now, or wait until you create your first project as covered in the Build your first SharePoint client-side web part (Hello World part 1): Preview the web part tutorial.

使用 Yeoman 生成器为 SharePoint 框架创建项目后,立即从项目的根文件夹执行以下命令。Once a project has been created with the Yeoman generator for the SharePoint Framework, execute the following command from within the root folder of the project.

gulp trust-dev-cert

备注

这样做的前提是,已在创建项目后使用 npm install 安装所有依赖项。This assumes you have installed all dependencies with npm install after creating the project. 这一步会将所有 Gulp 任务安装为项目的一部分。This step will install all gulp tasks as part of a project.

可选工具Optional tools

下面列出了一些可能也会用到的工具:Following are some tools that might come in handy as well:

SPFx 和 SharePoint Server 2016SPFx Development for SharePoint Server 2016

SharePoint Server 2016 使用 SharePoint 框架 (SPFx) v1.1。SharePoint Server 2016 uses the SharePoint Framework (SPFx) v1.1. 大约在 v1.1 发布时,NodeJS 正从 NodeJS v6.x 过渡到 v8.x。Around this the time of the v1.1 release, NodeJS was transitioning from NodeJS v6.x to v8.x. 在此更新中,NodeJS 引入了默认 HTTP 协议从 HTTP1 切换为 HTTP2 的更改。In this update, NodeJS introduced a change where the default changed from HTTP1 to HTTP2. SPFx v1.1 是针对 HTTP1(而非 HTTP2)编写的,因此这项更改影响了 SPFx v1.1 项目的本地 Web 服务器。SPFx v1.1 was written for HTTP1, not HTTP2, so this change impacted the local web server for SPFx v1.1 projects.

在 NodeJS v8.x 中,可以强制使用 HTTP1,方法是设置以下环境变量,以指示 NodeJS 使用 HTTP1,而不是默认的 HTTP2:NODE_NO_HTTP2=1In NodeJS v8.x, you can force HTTP1 by setting the following environment variable to instruct NodeJS to use HTTP1 instead of the default HTTP2: NODE_NO_HTTP2=1. 此环境变量仅存在于 NodeJS v8.x 中。This environment variable only exists in NodeJS v8.x. 因此,如果要生成用于 SharePoint Server 2016 的 SPFx 解决方案,应使用 NodeJS v8.x。Therefore, if you are building SPFx solutions for SharePoint Server 2016, you should use NodeJS v8.x.

此问题不会影响更高版本的 SPFx,因为这些版本已进行更新以支持 HTTPs。This issue does not impact later versions of SPFx because they have been updated to support HTTPs.

有关详细信息,请参阅问题 #1002For more information, refer to issue #1002.

后续步骤Next steps

现在可以生成首个客户端 Web 部件了!You are now ready to build your first client-side web part!

故障排除Troubleshooting

无法信任自签名开发证书Unable to Trust the Self-signed Development Certificate

如果使用的是 SharePoint Server 2016/SPFx v1.1,请先查看前面的 SPFx 和 SharePoint Server 2016 部分,确保运行的是受支持的 NodeJS 版本。If you are working with SharePoint Server 2016 / SPFx v1.1, first check the SPFx & SharePoint Server 2016 section above to ensure you are running a supported version of NodeJS.

在某些情况下,执行命令 gulp trust-dev-cert 不会按预期信任计算机上的自签名开发证书。In some cases, executing the command gulp trust-dev-cert, does not have the desired effect of trusting the self-signed development certificate on your machine. 在此类极少数情况下,可能需要删除在配置文件文件夹中生成的隐藏文件夹。In rare cases such as these, you may need to delete a hidden folder that's generated in your profile folder. 先找到并删除文件夹 <homedir>/.gcb-serve-data,再尝试重新信任自签名开发证书。Locate & delete the folder <homedir>/.gcb-serve-data and then try to trust the self-signed development certificate again.

无法使用 NPM 安装包 - 企业代理Unable to Install Packages with NPM - Corporate Proxies

如果开发环境位于企业代理后面,需要将 NPM 配置为使用企业代理。If your development environment is behind a corporate proxy, you need to configure NPM to use that proxy. 请参阅 npm-config 文档,了解如何配置企业代理后面的开发环境,尤其是 proxy & http-proxy 设置。Refer to the npm-config documents on how to configure your development environment behind a corporate proxy... specifically the proxy & http-proxy settings. 更多信息:如何设置企业 Web 代理后面的 Node.js 和 NpmMore information: How to setup Node.js and Npm behind a corporate web proxy

备注

如果发现本文档或 SharePoint 框架有问题,请使用 sp-dev-docs 存储库上的问题列表,向 SharePoint 工程团队报告问题。If you find an issue in the documentation or in the SharePoint Framework, report that to SharePoint engineering by using the issue list at sp-dev-docs repository. 提前感谢读者提供反馈意见。Thanks for your input in advance.