# PM2 启动问题

URL: https://caijiao.org/pm2/troubleshooting/startup-issues
Source: docs/pm2/troubleshooting/startup-issues.md
Description: 解决 PM2 启动过程中常见的问题，包括进程启动失败、环境配置错误、端口冲突等，确保 Node.js 应用能够顺利启动并稳定运行。

PM2 是一个功能强大的进程管理工具，但在使用过程中，有时可能会遇到启动问题。无论是进程启动失败、环境配置错误，还是依赖缺失等问题，了解常见问题和解决方案能帮助你快速排查并解决问题，确保 Node.js 应用能够顺利启动并稳定运行。

## 1. **进程启动失败**

在使用 PM2 启动应用时，如果出现进程启动失败的情况，通常是由以下几种原因造成的：

### 常见原因

- **应用的启动脚本路径错误**：PM2 可能找不到应用的入口文件。
- **缺少必要的依赖**：应用可能依赖某些模块或库，但这些依赖没有被正确安装。
- **应用崩溃或退出**：应用在启动过程中出现异常，导致进程退出。

### 解决方法

- **检查脚本路径**：确保在 `ecosystem.config.js` 配置文件中正确指定了启动脚本的路径。例如，`script: './app.js'` 应该指向正确的应用入口文件。
- **安装缺失依赖**：运行 `npm install` 或 `yarn install` 安装缺失的依赖。
- **查看 PM2 日志**：使用 `pm2 logs <app-name>` 查看应用的错误日志，分析启动失败的具体原因。

```bash
pm2 logs my-app
````

查看日志输出，通常可以找到导致进程启动失败的错误信息。

## 2. **端口冲突**

如果应用绑定的端口已被其他进程占用，PM2 启动时会失败。端口冲突通常发生在开发环境中，当你多次启动应用或有其他服务在使用相同端口时。

### 解决方法

- **查看端口占用情况**：使用 `lsof` 或 `netstat` 查看端口是否被占用。

```bash
lsof -i :3000
```

如果发现端口被占用，可以尝试停止占用端口的进程，或者将应用配置为使用不同的端口。

- **修改应用的端口号**：在应用的配置中修改端口号，确保没有冲突。

### 示例：修改端口号

在 `ecosystem.config.js` 文件中，使用环境变量配置端口号：

```javascript
module.exports = {
  apps: [
    {
      name: 'my-app',
      script: './app.js',
      env: {
        NODE_ENV: 'development',
        PORT: 3000,  // 设置端口
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: 8000,  // 设置生产环境端口
      },
    },
  ],
};
```

在应用代码中，确保使用 `process.env.PORT` 获取端口号，并根据环境变量设置。

## 3. **权限问题**

有时，启动 PM2 时可能会遇到权限不足的问题，特别是在 Linux 或 macOS 上。当你尝试使用 PM2 启动应用时，可能会因为缺少写入权限或执行权限而导致启动失败。

### 解决方法

- **使用 `sudo` 权限**：如果你遇到权限问题，可以尝试使用 `sudo` 命令以管理员身份运行 PM2。

```bash
sudo pm2 start app.js
```

- **检查文件和目录权限**：确保 PM2 有权限读取和写入应用的目录和文件。

```bash
chmod -R 755 /path/to/your/app
```

## 4. **环境变量未正确配置**

如果在启动应用时，PM2 未正确加载环境变量，应用可能无法找到必要的配置或依赖，导致启动失败。通常这种情况发生在生产环境中，环境变量没有正确传递给应用。

### 解决方法

- **在 `ecosystem.config.js` 中配置环境变量**：确保在 `ecosystem.config.js` 中配置了正确的 `env` 和 `env_production` 环境变量。

```javascript
module.exports = {
  apps: [
    {
      name: 'my-app',
      script: './app.js',
      env: {
        NODE_ENV: 'development',
        DATABASE_URL: 'http://localhost:5432',
      },
      env_production: {
        NODE_ENV: 'production',
        DATABASE_URL: 'http://prod-db-url:5432',
      },
    },
  ],
};
```

- **使用 `.env` 文件**：在应用根目录下创建一个 `.env` 文件，使用环境变量文件管理配置。你可以使用 `dotenv` 包来加载 `.env` 文件。

```bash
npm install dotenv
```

在应用代码中加载环境变量：

```javascript
require('dotenv').config();
console.log(process.env.DATABASE_URL);
```

## 5. **PM2 启动日志查看与排错**

当 PM2 启动失败时，查看应用的日志是排查问题的重要步骤。PM2 提供了强大的日志查看功能，可以帮助你定位错误。

### 查看日志

```bash
pm2 logs my-app
```

使用 `pm2 logs` 可以查看应用的输出日志，通常日志中会显示应用启动失败的原因，帮助你快速找到问题所在。

### 调试启动问题

- **查看 PM2 系统日志**：如果没有看到有用的错误信息，可以查看 PM2 系统日志。

```bash
pm2 logs --lines 1000
```

此命令将显示最近的 1000 行日志，便于你分析应用启动时的具体情况。

## 6. **总结**

PM2 启动问题通常与应用的配置、环境变量、端口冲突、权限设置等因素有关。通过查看 PM2 的日志、确认环境配置和依赖、解决端口冲突等问题，通常可以解决大部分启动失败的问题。

遇到启动问题时，按照以下步骤排查：

1. 查看启动日志，确认错误信息。
2. 检查端口是否被占用，必要时修改端口号。
3. 确保环境变量正确配置，尤其是在生产环境中。
4. 检查文件和目录的权限，确保 PM2 有足够的权限操作。
5. 尝试重新启动 PM2，查看是否能够解决问题。

通过这些方法，你可以有效解决 PM2 启动过程中遇到的问题，确保 Node.js 应用能够顺利启动并持续运行。