WebStorm环境搭建与首次代码运行指引-webstorm-PHP中文网

webstorm 运行项目需确保本地环境链路完整：node 和 npm 命令可用、package.json 含有效 scripts、working directory 正确、.env 被正确加载，且所有配置最终依赖终端可执行性。

webstorm环境搭建与首次代码运行指引

WebStorm 能直接运行 Node.js 或前端项目，但前提是本地环境链路必须完整打通——node 命令能执行、npm 或 cnpm 可安装依赖、项目有可识别的启动脚本。缺任一环，点绿色三角形都会失败。

很多人卡在这一步：明明装了 Node.js，但 WebStorm 里报错 Command 'node' not found 或终端里输 node -v 提示“不是内部或外部命令”。这不是 WebStorm 的问题，而是系统没认出 node。

打开命令行（CMD/PowerShell/Terminal），单独执行 node -v 和 npm -v —— 必须都返回版本号才算通过
如果失败，说明 Node.js 安装路径没进系统 PATH 环境变量。Windows 用户请检查“系统属性 → 高级 → 环境变量”，在 Path 里添加 Node.js 安装目录（如 C:\Program Files\nodejs\）
别信“安装器自动配置”——某些解压版或自定义路径安装不会自动加 PATH，必须手动补
改完环境变量后，**必须新开一个命令行窗口再测试**，旧窗口不继承新变量

WebStorm 的“运行配置”本质是调用 npm run xxx，它只认 package.json 里 scripts 字段定义的命令。没有对应字段，点运行就报错 Missing script。

WebStorm Linux版

WebStorm 2026.2 Linux tar.gz 安装包，适合在 Linux 桌面环境中搭建现代前端开发与调试工作流。

下载

打开项目根目录下的 package.json，确认存在类似这样的字段：

"scripts": {
  "dev": "vite",
  "start": "node server.js",
  "serve": "webpack serve"
}

不同项目脚手架命令名不同：vue-cli 默认用 npm run serve，Vite 项目常用 npm run dev，Create React App 是 npm start
WebStorm 新建运行配置时，在 Package.json script 下拉框里选不到命令？先检查 package.json 是否被 IDE 识别为普通文本——右键文件 → Override file type → 选 JSON
若用 cnpm，需在 WebStorm 运行配置中把 Node interpreter 指向 cnpm 所在路径（通常为 %USERPROFILE%\AppData\Roaming\npm\cnpm.cmd），否则仍走默认 npm

控制台显示服务已启动（如 Local: http://localhost:5173/），但浏览器空白或报 ERR_CONNECTION_REFUSED，大概率是端口被占或跨域拦截。

先确认服务真起来了：在终端里手动执行一遍 npm run dev，看是否有 ready in XXX ms 或类似提示。没有就说明脚本本身有问题
端口冲突常见于多人共用开发机，或上一个项目没关干净。查占用：netstat -ano | findstr :5173（Windows）或 lsof -i :3000（macOS/Linux），杀掉对应 PID
Vue/Vite 项目默认不启用跨域代理，但如果你用 file:// 直接打开 index.html，会因浏览器安全策略报错。必须通过 localhost 访问，不能双击 HTML 文件
WebStorm 内置浏览器有时缓存旧页面，建议用 Chrome/Firefox 手动访问地址，或在 WebStorm 运行配置里勾选 After launch → Open in browser 并指定 URL

控制台输出 Server running on http://localhost:3000，但接口返回 500 或连接超时，问题往往不在 WebStorm，而在 Node 进程的运行上下文。

检查 .env 文件是否被加载：Node.js 默认不读 .env，需靠 dotenv 包。确保代码开头有 require('dotenv').config()，且 .env 在项目根目录
数据库连接字符串里的 localhost 在 Docker 环境下可能指向容器内网，而非宿主机。改用 host.docker.internal（Docker Desktop）或具体 IP
WebStorm 的 Node.js 运行配置里，Working directory 必须设为项目根目录，否则 require('./config/db') 会找不到文件
如果用了 nodemon，确保 WebStorm 运行配置的 Node interpreter 指向全局 nodemon（如 %USERPROFILE%\AppData\Roaming\npm\nodemon.cmd），而不是 node