Office.js SSO项目Webpack Dev Server启动异常求助

环境信息 #

• generator-office 1.9.2
• node v16.16.0
• npm v8.11.0
• VS Code Version: 1.71.2
• Windows 10 x64 (19044)
• webpack@5.74.0

问题描述 #

项目曾正常运行，适配需求后可成功构建，但执行npm start（脚本包含build:dev、start:server、sideload）时终端报错：

Starting the dev server... (webpack serve --mode development)
Unable to start the dev server. Error: The dev server is not running on port 3000.

更换端口至3001后问题依旧。未关闭首个终端时再次执行npm start，Webpack编译成功且自动切换端口，但无法访问页面；Excel可加载插件，但调试配置不符合标准，需恢复正常调试流程。

已尝试操作 #

• 确认Webpack编译输出成功
• 检查%LocalAppData%\npm-cache\_logs及%LocalAppData%\Temp\OfficeAddins.log.txt日志
• 重启相关进程
• 用netstat -ano | findstr :3000检查端口占用
• 执行office-addin-lint check排查代码错误
• 用npx office-addin-dev-certs verify验证Office开发证书
• 执行npm update更新依赖

进一步排查与解决方法 #

1. 直接调试Webpack Dev Server #

跳过npm脚本，直接执行webpack serve --mode development，观察终端完整输出。这能避免脚本串联执行时的错误隐藏，排查是否存在配置或依赖导致的启动异常。

2. 检查Webpack Dev Server配置 #

打开webpack.config.js，确认以下配置项：

• devServer.host是否设为localhost，避免因主机配置异常导致端口检测失败
• devServer.allowedHosts是否设为'all'，防止主机白名单限制
• devServer.static指向的目录是否正确（需匹配构建输出目录，通常为dist）
• 确认未设置冲突的devServer.open或devServer.hot配置，导致启动流程阻塞

3. 排查Office Addin Dev Server兼容性 #

执行npm list office-addin-dev-server查看依赖版本，该包与webpack@5存在版本兼容要求（需4.0.0及以上版本）。若版本不兼容，执行：

npm install office-addin-dev-server@latest --save-dev

之后单独执行npx office-addin-dev-server --port 3000 --path dist，验证dev server能否独立启动。

4. 彻底清理依赖与进程 #

• 强制终止所有Node.js进程：

  taskkill /F /IM node.exe
  

• 执行npm clean-install完全重新安装依赖，清除缓存中损坏的包文件

5. 调整Sideload时序与调试配置 #

• 拆分npm脚本，分步执行：先运行npm run build:dev，确认构建完成后执行npm run start:server，待终端明确显示dev server启动成功后，再手动执行sideload脚本，排查是否因时序问题导致端口检测失败
• 检查.vscode/launch.json中的调试配置，确认url指向正确端口，webRoot与项目结构匹配，示例配置：

  {
      "name": "Excel Desktop",
      "type": "node",
      "request": "launch",
      "program": "${workspaceRoot}/node_modules/office-addin-debugging/lib/start.js",
      "args": [
          "--manifest", "${workspaceRoot}/manifest.xml",
          "--debug", "true"
      ],
      "console": "integratedTerminal"
  }
  

6. 重新生成并验证HTTPS证书 #

执行以下命令重新生成开发证书，确保证书配置正确：

npx office-addin-dev-certs install

重启VS Code与终端后，再次尝试启动项目。

内容的提问来源于stack exchange，提问作者plagwitz