为何执行npm run dev无法启动Frontity项目本地服务器？

问题说明 #

搭建Frontity项目本地服务器时，执行npm run dev命令无法启动服务；直接执行npx frontity dev也报错。项目package.json的脚本配置如下：

"scripts": {
  "dev": "frontity dev",
  "build": "frontity build",
  "serve": "frontity serve"
}

排查修复步骤 #

• 重装项目依赖

  1. 删除项目根目录的node_modules文件夹
  2. 删除package-lock.json文件（使用yarn的话删除yarn.lock）
  3. 执行npm install重新拉取所有依赖
  4. 再次运行npm run dev测试

• 验证Node.js版本
  Frontity要求Node.js版本不低于14.x（推荐使用18.x等LTS版本）。执行node -v查看当前版本，版本不符时可通过nvm等工具切换至兼容版本。

• 检查端口占用情况
  Frontity默认使用3000端口，若该端口被其他程序占用会导致启动失败：

  • Windows系统执行：netstat -ano | findstr :3000
  • macOS/Linux系统执行：lsof -i :3000
    关闭占用端口的进程，或指定其他端口启动：

  npx frontity dev --port 3001
  

• 全局安装Frontity CLI
  执行npm install -g frontity全局安装Frontity命令行工具，确保frontity命令可被系统识别，之后再尝试启动服务。

• 检查项目配置文件
  确认项目根目录的frontity.settings.js无语法错误或无效配置，可临时替换为官方基础配置文件测试是否能正常启动。

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