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

在开发过程中，我们可能会遇到端口占用的问题，尤其是当多个进程或服务尝试监听同一个端口时。最近在运行 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，然后重新安装依赖并启动开发环境：
bash 复制代码
```
rm -rf node_modules dist .vite build
npm install
npm run dev
```
使用 grep 辅助全局搜索

为了避免在未来的开发中再次遇到类似问题，我改用了 grep 来进行更为彻底的搜索。grep 比 VSCode 更强大，能够确保搜索到项目中的每一个文件：
bash 复制代码
```
grep -rn "9005" .
```
确保项目配置文件被正确引用

最后，我还检查了 .gitignore 配置，确保项目中的配置文件（如 workspace.config.js）不会被忽略。

总结

这个问题的根本原因是端口配置未彻底修改，并且由于间接引用的配置文件未被正确捕捉到，导致我们修改的端口并未生效。通过以下几个步骤，我成功解决了这个问题：

确保所有配置文件都修改正确 ：包括间接引用的文件，如 workspace.config.js。
清理缓存和依赖 ：删除 node_modules 和构建产物，重新安装依赖。
加强搜索手段 ：使用 grep 进行更为彻底的全局搜索，避免遗漏配置。
优化配置文件管理 ：确保项目配置文件不被 .gitignore 排除，保持其可访问性。

希望本文能帮助大家更好地理解端口占用问题的根本原因，并提供有效的解决方案。在开发过程中，确保所有配置文件的修改彻底且一致，是避免类似问题的关键。