m365pnp/spfx Docker 镜像 - 轩辕镜像

SharePoint Framework Docker镜像文档

镜像概述

本Docker镜像用于运行SharePoint Framework（简称SPFx），提供了预配置的开发环境，无需在主机系统上直接安装SPFx依赖。通过容器化方式，可快速搭建隔离的SPFx开发环境，支持项目文件映射到主机系统，便于版本控制和文件管理。

核心功能与特性

• 预安装开发工具：包含SPFx Yeoman生成器及相关依赖，可直接创建和开发SPFx项目
• 多版本支持：提供多个标签对应不同SPFx版本，满足不同项目需求
• 文件系统映射：项目文件存储在主机目录，支持直接通过主机工具编辑和版本控制
• 端口映射：默认映射开发所需端口（4321用于工作区，35729用于热重载）
• 跨平台兼容：支持macOS、Windows等主流操作系统的Docker环境

使用场景

• SharePoint Framework项目的快速初始化与开发
• 多版本SPFx项目并行开发（通过不同镜像标签切换环境）
• 避免主机环境依赖冲突，保持开发环境一致性
• 团队协作中统一开发环境配置

使用方法

前置准备

• 确保Docker已安装并运行
• 在Docker设置 > 共享驱动器中，验证项目所在驱动器已启用共享

启动容器

根据操作系统和shell环境，执行以下命令：

macOS（命令行）

sh
cd [你的项目目录]
docker run -it --rm --name ${PWD##*/} -v $PWD:/usr/app/spfx -p 4321:4321 -p 35729:35729 m365pnp/spfx

Windows PowerShell

PowerShell
cd [你的项目目录]
docker run -it --rm --name spfx-helloworld -v ${PWD}:/usr/app/spfx -p 4321:4321 -p 35729:35729 m365pnp/spfx

Windows 其他shell（如cmd）

cmd
cd [你的项目目录]
docker run -it --rm --name spfx-helloworld -v %cd%:/usr/app/spfx -p 4321:4321 -p 35729:35729 m365pnp/spfx

开发项目

容器启动后，即可像在本地安装SPFx一样操作：

1. 在容器命令行中执行以下命令创建新项目：

   sh
   yo @microsoft/sharepoint
   

2. 生成器创建的所有文件将存储在主机的项目目录中，可直接提交到版本控制

退出容器

在容器命令行中执行以下命令关闭容器：

sh
exit

可用标签

镜像提供以下标签，对应不同版本的SharePoint Framework Yeoman生成器：

• latest：包含1.21.1版本的SPFx Yeoman生成器
• online：包含1.21.1版本的SPFx Yeoman生成器
• onprem：包含1.4.1版本的SPFx Yeoman生成器
• 1.21.1：包含1.21.1版本的SPFx Yeoman生成器
• 1.21.0：包含1.21.0版本的SPFx Yeoman生成器
• 1.20.0：包含1.20.0版本的SPFx Yeoman生成器
• 1.19.0：包含1.19.0版本的SPFx Yeoman生成器
• 1.18.2：包含1.18.2版本的SPFx Yeoman生成器
• 1.18.1：包含1.18.1版本的SPFx Yeoman生成器
• 1.18.0：包含1.18.0版本的SPFx Yeoman生成器
• 1.17.4：包含1.17.4版本的SPFx Yeoman生成器
• 1.17.3：包含1.17.3版本的SPFx Yeoman生成器
• 1.17.2：包含1.17.2版本的SPFx Yeoman生成器
• 1.17.1：包含1.17.1版本的SPFx Yeoman生成器
• 1.17.0：包含1.17.0版本的SPFx Yeoman生成器
• 1.16.1：包含1.16.1版本的SPFx Yeoman生成器
• 1.16.0：包含1.16.0版本的SPFx Yeoman生成器
• 1.15.2：包含1.15.2版本的SPFx Yeoman生成器
• 1.15.0：包含1.15.0版本的SPFx Yeoman生成器
• 1.14.0：包含1.14.0版本的SPFx Yeoman生成器
• 1.13.1：包含1.13.1版本的SPFx Yeoman生成器
• 1.13.0：包含1.13.0版本的SPFx Yeoman生成器
• 1.12.1：包含1.12.1版本的SPFx Yeoman生成器
• 1.12.0：包含SPFx 1.12.0版本的Yeoman生成器
• 1.11.0：包含1.11.0版本的SPFx Yeoman生成器
• 1.10.0：包含1.10.0版本的SPFx Yeoman生成器
• 1.9.1：包含1.9.1版本的SPFx Yeoman生成器
• 1.8.2：包含1.8.2版本的SPFx Yeoman生成器
• 1.8.1：包含1.8.1版本的SPFx Yeoman生成器
• 1.8.0：包含1.8.0版本的SPFx Yeoman生成器
• 1.7.1：包含1.7.1版本的SPFx Yeoman生成器
• 1.7.0：包含1.7.0版本的SPFx Yeoman生成器
• 1.6.0：包含1.6.0版本的SPFx Yeoman生成器
• 1.5.1：包含1.5.1版本的SPFx Yeoman生成器
• 1.5.0：包含1.5.0版本的SPFx Yeoman生成器
• 1.4.1：包含1.4.1版本的SPFx Yeoman生成器
• 1.4.0：包含1.4.0版本的SPFx Yeoman生成器
• 1.3.4：包含1.3.4版本的SPFx Yeoman生成器
• 1.3.2：包含SPFx 1.3.2版本的Yeoman生成器
• 1.3.1：包含SPFx 1.3.1版本的Yeoman生成器
• 1.3.0：包含SPFx 1.3.0版本的Yeoman生成器
• 1.2.0：包含1.2.0版本的SPFx Yeoman生成器
• 1.1.3：包含SPFx 1.1.3版本的Yeoman生成器
• 1.1.1：包含1.1.1版本的SPFx Yeoman生成器
• 1.1.0：包含1.1.0版本的SPFx Yeoman生成器
• 1.0.2：包含SPFx 1.0.2版本的Yeoman生成器
• ga：包含GA版本的SPFx Yeoman生成器
• rc0：包含RC0版本的SPFx Yeoman生成器
• drop-6：包含developer preview drop 6版本的SPFx Yeoman生成器
• drop-5：包含developer preview drop 5版本的SPFx Yeoman生成器
• drop-4：包含developer preview drop 4版本的SPFx Yeoman生成器

已知问题

无法写入文件到磁盘

执行yo @microsoft/sharepoint时提示无法写入文件，通常是因为Docker未共享项目所在驱动器。解决方法：进入Docker > 设置 > 共享，启用项目所在驱动器的共享。

SharePoint Framework >=1.14.0无法访问workbench和bundle

使用SPFx >=v1.14.0版本时，无法访问本地workbench或加载bundle，原因是workbench默认映射到localhost，容器外部无法访问。解决方法：修改项目中的./config/serve.json文件为：

json
{
  "$schema": "[***]",
  "port": 4321,
  "ipAddress": "0.0.0.0",
  "https": true,
  "initialPage": "[***]"
}

SharePoint Framework >=1.6.0 <=1.13.1无法访问workbench和bundle

使用SPFx >=v1.6.0且<=v1.13.1版本时，类似问题的解决方法：修改./config/serve.json文件为：

json
{
  "$schema": "[***]",
  "port": 4321,
  "hostname": "0.0.0.0",
  "https": true,
  "initialPage": "[***]"
}

SharePoint Framework 1.13.1无法访问bundle

修改node_modules\@microsoft\spfx-heft-plugins\lib\plugins\webpackConfigurationPlugin\WebpackConfigurationGenerator.js:393：

原代码：

javascript
const debugBaseUrl = `${serveConfig.https ? 'https' : 'http'}://${serveConfig.hostname || 'localhost'}:${serveConfig.port || 4321}/${distFolderName}/`;

修改为：

javascript
const debugBaseUrl = `${serveConfig.https ? 'https' : 'http'}://localhost:${serveConfig.port || 4321}/${distFolderName}/`;

SharePoint Framework 1.12.1无法访问bundle

修改node_modules\@microsoft\spfx-heft-plugins\lib\plugins\webpackConfigurationPlugin\WebpackConfigurationGenerator.js:376：

原代码：

javascript
const debugBaseUrl = `${serveConfig.https ? 'https' : 'http'}://${serveConfig.hostname || 'localhost'}:${serveConfig.port || 4321}/dist/`;

修改为：

javascript
const debugBase