当前位置：首页 > news >正文

【Web】如何解决 `npm run dev` 报错 `address already in use 127.0.0.1:9005` 的问题

news 来源：原创 2025/4/30 7:27:33

在开发过程中，我们可能会遇到端口占用的问题，尤其是当多个进程或服务尝试监听同一个端口时。最近在运行 npm run dev 时，我遇到的错误是 address already in use 127.0.0.1:9005，这让我花了些时间才找到问题的根源。本文将总结该问题的背景、原因分析、解决办法，并给出一些优化建议，帮助大家避免类似的开发困境。

背景问题

在开发过程中，我使用了 npm run dev 启动本地开发环境，但在启动时，终端报错提示端口 9005 已经被占用：

address already in use 127.0.0.1:9005

尝试修改端口配置、清理缓存，甚至更改环境变量，但问题依旧存在，开发环境始终无法启动。经过一番排查，我最终找到了真正的原因。

原因分析

搜索和替换不彻底
初步排查时，我在 VSCode 中进行了全局搜索并替换了 9005 为 9006，但问题仍然没有解决。后来发现，VSCode 的全局搜索并没有覆盖到所有的文件。特别是在某些间接引用的文件（如 workspace.config.js）中，端口仍然被硬编码为 9005，这就是导致端口冲突的根本原因。
间接引用文件未被搜索到
在项目中，我使用了 Webpack 来构建，并且在 webpack.config.js 中引用了 workspace.config.js 文件。原以为在 webpack.config.js 中修改了端口即可，结果发现，workspace.config.js 中还是存在端口配置，而 VSCode 全局搜索没有正确捕捉到该文件的内容。
缓存未清理
另外，虽然我修改了配置，但由于项目中存在一些缓存文件（如 node_modules、dist、.vite 等），在某些情况下，修改的配置并没有被完全加载，导致依旧使用了旧的端口配置。

解决办法

经过详细排查后，以下是我最终采取的解决办法：

修改间接引用的配置文件
首先，我在 workspace.config.js 文件中将端口 9005 更改为 9006。这是最重要的一步，因为 webpack.config.js 引用了 workspace.config.js，且该文件中硬编码了端口号。
清理缓存并重新安装依赖
为了确保修改生效，我删除了项目中的缓存文件和 node_modules，然后重新安装依赖并启动开发环境：
```
rm -rf node_modules dist .vite build
npm install
npm run dev
```
使用 grep 辅助全局搜索
为了避免在未来的开发中再次遇到类似问题，我改用了 grep 来进行更为彻底的搜索。grep 比 VSCode 更强大，能够确保搜索到项目中的每一个文件：
```
grep -rn "9005" .
```
确保项目配置文件被正确引用
最后，我还检查了 .gitignore 配置，确保项目中的配置文件（如 workspace.config.js）不会被忽略。