Bug 解决 | 项目启动失败

想必所有学编程的同学都遇到过这样一个问题：把别人的代码或项目拉取到自己的电脑上，然后按照别人提供的步骤去启动项目。

结果当你自信满满地点击运行键时，就看到了：

这个时候，很多初学编程的同学就会慌了。为什么我和你的代码一样、操作一模一样，结果项目还启动失败了呢？

不要慌，这其实是一个非常普遍的问题，也很好解决。今天这篇文章就来分享一下如何解决它。

#项目启动失败原因

首先，运行一个项目，需要考虑以下几个要素：

1. 代码
2. 环境（系统、平台）
3. 依赖
4. 资源

只要保证这 4 个要素和其他成功运行的项目一致，那么 99.9% 的概率你也能成功运行项目！

#代码一致

首先是代码，这个没什么好说的，只要别人提供给你的代码是正确可运行的，直接用 git 版本控制工具 clone（拷贝）到本地即可。

#环境一致

然后是最最最最重要的环境！绝大多数情况下，都是因为你本地电脑的环境和其他同学的环境不一致，才导致了报错。

环境又包括系统、平台等。系统就是指 Windows、Linux、MacOS 等，如果是 Java 项目，因为 JVM 的存在，所以基本上不会出现系统不兼容的问题；但如果是其他不具备跨平台特性的语言，在 Win 上能跑的项目可能到 Linux 上就不能正确运行了，会出现各种各样隐藏的坑。

平台是指运行代码需要的基本环境，比如 Node.js、Java、.NET 等。对于平台来说，最重要的莫过于 版本 了，如果版本不兼容，那么项目就很容易运行不起来，或者有很多奇奇怪怪的错误。

就拿我给大家开源的项目代码来说，有的同学能运行，有的同学就不能运行，多半是环境版本的问题。

比如在安装了 Java 17 的电脑上去跑 Java 8 的后端代码，在 Node 10 的电脑上去跑 Node 16 的前端代码等等。

一般情况下，目前还是建议后端同学用 Java 8 和 Spring Boot 2，前端同学用 Node.js >= 16 的版本，别去追求太高的版本，否则出了问题后果自负。

#依赖一致

除了环境外，我们在安装项目依赖时，也同样需要注意版本。举个例子，对于前端项目来说，有些项目依赖的版本定义可能并不明确，如下图：

版本号前的 ^ 的意思是版本号的末尾可以变化，所以你实际安装的版本可能和其他更早安装的依赖版本不一致，有可能就会出现代码冲突、不兼容。

所以前端项目一般会使用 package-lock.json 文件来锁住依赖的版本号，保证不同开发人员在不同时间拉取依赖时版本都是一致的。

而 Java 后端项目相对就简单了一些，我们写 Maven（Gradle）依赖时一般都指定一个明确的版本号，不存在版本号不一致导致的冲突。

如果 jar 包之间冲突的话，那又是另一个故事了，可以用 Maven Helper 解决一下。

所以，如果你是跟着别人的视频教程或直接下载源码启动项目，请确保你的本地环境、依赖版本和作者的一致。一般在文档上都有明确的说明，可不要做个小马虎，跳着去看别人的文档哦。

#资源一致

除了环境之外，还有一个很不起眼的因素，就是资源，像 CPU、内存、硬盘容量等等。

比如项目需要至少 8 G 内存、10 G 硬盘，结果你的电脑只有 4 G 内存、硬盘也不够了，那么项目要么运行不起来，要么就是后期出现各种奇奇怪怪的问题。

#其他因素

除了上述几个因素外，还有一些可能影响项目启动的其他因素，比如：

1）运行所需的依赖没有启动。比如后端项目运行前一般都要启动数据库、Redis 等，可以通过认真阅读报错信息并百度来定位到问题。

2）网络环境不一致。比如在公司的内网环境无法拉取到外网的依赖，自家网络无法拉取到国外的依赖镜像等。典型的就是 NPM 依赖或 Maven 依赖安装失败，此类报错会有明显的 “网络连接错误” 的提示，直接百度就能解决此类问题。

3）系统权限问题。一般此类问题会有明显的 “permission” 相关的报错信息，直接百度就能解决此类问题。

建议不要把项目放到系统目录中，或者可以使用管理员权限、sudo 命令（Linux / Mac 用户）来执行安装依赖、启动项目等可能需要更高权限的命令。

4）其他细节问题。比如在存放项目代码的任何路径中，尽量不要出现中文，也可能会影响项目的运行。

#推荐的解决方案

综上，我们如果拉下来别人的开源项目学习、跟着视频教程学习、或者是拉取公司的项目开发前，最先要做的事情是阅读官方文档 来确定项目运行的环境、依赖版本、需要的资源、运行条件等关键信息，跟安装游戏和软件一样的，一定要认真了解。

以开源知识库 wiki.js 项目为例，很明确地指出了这些要求：

阅读官方文档真的是非常重要的！

如果认真按照官网文档的要求进行了操作，却还是无法启动项目，就要收集尽可能多地报错信息，从中找到一些关键词去百度或询问 AI。对于开源项目，可以去框架的 Github Issues 区去搜一下，比如 Ant Design Pro 框架 (opens new window)。