M系列芯片Mac上通过Homebrew一键安装/卸载Nginx并上线项目全指南

大家好，我是袁庭新。如何在MacBook Pro（Apple Silicon）上，通过Homebrew安装Nginx/卸载Nginx，以及手把手教你在Apple Silicon Mac上丝滑运行Nginx项目，看这一篇就够了！

1 如何安装Nginx

1.1 检查是否安装Nginx

在macOS上，你可以通过以下几种方式来检查是否已经安装了Nginx。

1.1.1 使用which命令

如果返回类似/usr/local/bin/nginx或/opt/homebrew/bin/nginx的路径，说明已安装。

复制代码

yuanxin@yuantingxin-MacBookPro ~ % which nginx
/opt/homebrew/bin/nginx

如果没有输出，可能未安装，或者不在$PATH中。

1.1.2 使用nginx -v

在终端输入以下命令：

复制代码

yuanxin@yuantingxin-MacBookPro ~ % nginx -v

如果已安装，会显示 Nginx 的版本号，例如：

复制代码

nginx version: nginx/1.27.4

如果提示command not found，则说明未安装或未加入环境变量。

1.1.3 检查Homebrew

如果你是用Homebrew安装的，可以在终端输入以下命令：

复制代码

yuanxin@yuantingxin-MacBookPro ~ % brew list | grep nginx
nginx

如果你通过Homebrew安装过Nginx，这条命令会列出nginx。

这里需要注意的是：Apple Silicon（M1/M2/M3）芯片的Mac默认Homebrew安装路径是/opt/homebrew，而Intel芯片的是/usr/local。

1.1.4 检查进程是否正在运行

在终端输入以下命令：

复制代码

yuanxin@yuantingxin-MacBookPro ~ % ps aux | grep nginx
nobody           22109   0.0  0.0 411152768    560   ??  S     2 226    0:00.04 nginx: worker process  
root             22106   0.0  0.0 410890624      0   ??  Ss    2 226    0:00.03 nginx: master process /opt/homebrew/opt/nginx/bin/nginx -g daemon off;  
yuanxin           9131   0.0  0.0 410733264   1504 s000  S+    3:27下午   0:00.00 grep nginx

如果Nginx正在运行，你会看到master和worker进程。

或者用下面的命令查看80端口是否被Nginx占用（默认HTTP端口）。

复制代码

sudo lsof -i :80

1.2 通过Homebrew安装Nginx

在MacBook Pro (Apple Silicon)上，Homebrew默认安装在/opt/homebrew，安装过程非常直接。请按照以下步骤操作。

第一步：更新Homebrew

在安装之前，建议先更新Homebrew的公式列表，以确保安装的是最新稳定版本的Nginx。

复制代码

brew update

第二步：安装Nginx

执行以下命令进行安装：

复制代码

brew install nginx

说明：

Homebrew会自动下载Nginx及其依赖项（如OpenSSL、PCRE等）。
安装完成后，终端会显示一些重要的提示信息（例如配置文件路径、默认端口等），请务必留意这些输出。

第三步：验证安装

安装完成后，检查Nginx是否安装成功以及版本号：

复制代码

nginx -v

预期结果：应显示类似"nginx version: nginx/1.29.x ..."的信息。

第四步：启动Nginx服务

Homebrew安装的Nginx默认不会自动随系统启动，你需要手动启动它。推荐使用"brew services"来管理，这样它可以作为后台守护进程运行，并在开机时自动启动。

复制代码

# 启动Nginx服务
brew services start nginx

启动后，你可以验证服务状态：

复制代码

brew services list

预期结果：nginx的状态应显示为started。

第五步：测试运行

打开浏览器访问http://localhost:8080或http://127.0.0.1:8080。

注意Homebrew版Nginx默认监听端口通常是8080，而不是标准的80端口（因为普通用户权限无法直接绑定80端口，除非配置特殊权限）。
如果看到"Welcome to nginx!"页面，说明安装并运行成功。

2 Nginx服务管理常用命令

2.1 启动Nginx并设置开机自启

在终端输入以下命令：

复制代码

brew services start nginx

这会以后台服务方式启动Nginx。同时会将Nginx添加到登录项，实现开机自启动。

配置文件默认位置：

Apple Silicon (M1/M2/M3): /opt/homebrew/etc/nginx/nginx.conf
Intel Mac: /usr/local/etc/nginx/nginx.conf

2.2 仅临时启动

如果你不想让它开机自启，只是临时运行一次：

复制代码

nginx

注意：这种方式关闭终端后Nginx可能会退出（除非用nohup或&后台运行）。

2.3 其他常用命令

其他常用命令总结见下：

|-------------|----------------------------------|
| 操作 | 命令 |
| 停止Nginx | brew services stop nginx |
| 重启Nginx | brew services restart nginx |
| 查看状态 | brew services list | grep nginx |
| 重载配置（不中断服务） | nginx -s reload |

注意：修改配置后，推荐用nginx -s reload重载，而不是重启整个服务。

2.4 验证是否启动成功

打开浏览器访问以下地址，如果看到"Welcome to nginx!"页面，说明启动成功。

复制代码

http://localhost

或者用命令行检查：

复制代码

curl -I http://localhost

应该返回类似：

复制代码

HTTP/1.1 200 OK
Server: nginx/...

3 部署项目

3.1 构建你的前端项目

确保你已经生成了生产环境的静态文件（通常是dist或build文件夹）。例如：

复制代码

# Vue项目
npm run build

# React项目
npm run build

这会生成一个类似your-project/dist/的目录，里面包含index.html、static/、assets/等文件。

3.2 将构建产物复制到Nginx能访问的目录

创建一个专门的目录存放你的项目。

复制代码

# 例如，创建一个web目录（你可以自定义路径）
mkdir -p ~/web/my-frontend-app

# 复制构建产物进去（假设你的构建输出在"./dist"）
cp -r ./dist/* ~/web/my-frontend-app/

3.3 修改Nginx配置文件

Nginx默认配置只服务一个站点。你需要修改它的配置来指向你的项目。

找到配置文件位置：

Apple Silicon (M1/M2/M3)：/opt/homebrew/etc/nginx/nginx.conf
Intel Mac：/usr/local/etc/nginx/nginx.conf

编辑主配置或添加server块。

3.3.1 方法A：直接修改nginx.conf（简单场景）

打开配置文件：

复制代码

nano /opt/homebrew/etc/nginx/nginx.conf   # Apple Silicon
# 或
nano /usr/local/etc/nginx/nginx.conf      # Intel

找到server { ... }块（通常在http { ... }内部），修改root和index：

复制代码

server {
    listen       8080;               # 改成8080避免权限问题（推荐）
    server_name  localhost;

    root   /Users/你的用户名/web/my-frontend-app;  # 替换成你的实际路径！
    index  index.html;

    location / {
        try_files $uri $uri/ /index.html;  # 支持前端路由（如Vue Router history模式）
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   html;
    }
}

注意：

把/Users/你的用户名/...替换成你的真实路径（用pwd查看）。
使用绝对路径！Nginx不识别~。
try_files是关键，用于支持SPA（单页应用）的前端路由。

3.3.2 方法B：使用独立的server配置文件（推荐用于多项目）

在/opt/homebrew/etc/nginx/servers/（或/usr/local/etc/nginx/servers/）下创建新文件：

复制代码

mkdir -p /opt/homebrew/etc/nginx/servers
nano /opt/homebrew/etc/nginx/servers/my-frontend-app.conf

内容如下：

复制代码

server {
    listen 8080;
    server_name localhost;

    root /Users/你的用户名/web/my-frontend-app;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

确保主nginx.conf中包含这一行（Homebrew默认已启用）：

复制代码

include servers/*;

3.4 重载Nginx配置

保存配置后，重载Nginx（无需重启）：

复制代码

nginx -s reload

如果提示找不到命令，可以先用：

复制代码

brew services restart nginx

打开浏览器，访问：

复制代码

http://localhost:8080

你应该就能看到你的前端项目了！

4 常见问题排查

4.1 常见错误类型

项目在运行时可能会出现以下的问题，对应的解决方法见下表。

|----------------|----------------------------------------------|
| 问题 | 解决方法 |
| 403 Forbidden | 检查文件夹权限：chmod -R 755 ~/web/my-frontend-app |
| 404 Not Found | 检查root路径是否正确，是否包含index.html |
| 刷新页面404（SPA路由） | 确保有try_files $uri $uri/ /index.html; |
| 端口被占用 | 换个端口，比如listen 8081; |

4.2 检查具体的错误日志

比如Nginx在启动时提示"256 "退出代码（Exit Code）的问题，这通常是一个通用错误码，意味着进程异常终止，具体原因需要看日志。

退出代码256只是告诉我们"失败了"，具体为什么失败需要看Nginx自己的错误日志。请在终端运行：

复制代码

# 查看Nginx错误日志的最后20行
# 注意：路径可能因Intel芯片(/usr/local)或Apple芯片(/opt/homebrew)而异
tail -n 20 /opt/homebrew/var/log/nginx/error.log
# 如果上面文件不存在，尝试：
tail -n 20 /usr/local/var/log/nginx/error.log

在重启服务前，先确保配置文件没有语法错误：

复制代码

nginx -t

如果显示syntax is ok和test is successful，则配置没问题；如果有报错，请根据提示修改配置文件。

5 如何干净卸载Nginx

要干净卸载Nginx（包括程序、配置文件、日志和服务注册），请按照以下步骤操作：

5.1 停止并卸载Nginx服务

首先，需要停止正在运行的Nginx服务并从Homebrew的服务管理中移除它，然后卸载软件本身。

在终端中依次执行以下命令：

复制代码

# 1.停止Nginx服务(如果正在运行)
brew services stop nginx

# 2.强制杀死可能残留的Nginx进程(以防万一)
sudo pkill nginx

# 3.卸载Nginx主程序
brew uninstall nginx

# 4.(可选)清理Homebrew缓存和依赖
brew cleanup
brew autoremove

注意：brew uninstall nginx通常不会删除你的配置文件（nginx.conf）和日志文件，这是为了保留用户数据。若要"干净"卸载，必须手动执行下一步。

5.2 手动删除残留配置和数据文件

为了实现彻底干净的卸载，你需要手动删除Homebrew留下的配置目录、日志目录以及网页根目录。

在Mac（Apple Silicon）上，这些文件通常位于/opt/homebrew/etc/和/opt/homebrew/var/。请执行以下命令：

复制代码

# 1.删除配置文件目录(包含nginx.conf等)
sudo rm -rf /opt/homebrew/etc/nginx

# 2.删除日志文件目录
sudo rm -rf /opt/homebrew/var/log/nginx

# 3.删除默认的网页根目录(如果你没有在里面存放重要数据)
sudo rm -rf /opt/homebrew/var/www

# 4.(可选)检查并删除启动项plist文件(通常brew services stop已处理，但可再次确认)
# 用户级启动项
rm -f ~/Library/LaunchAgents/homebrew.mxcl.nginx.plist
# 系统级启动项
sudo rm -f /Library/LaunchDaemons/homebrew.mxcl.nginx.plist

5.3 验证卸载结果

执行完上述步骤后，可以通过以下命令验证是否卸载干净。

1.检查命令是否存在：

复制代码

nginx -v

预期结果：终端应提示"command not found: nginx"。

2.检查配置文件是否消失：

复制代码

ls /opt/homebrew/etc/nginx

预期结果：终端应提示"No such file or directory"。

3.检查服务状态：

复制代码

brew services list

预期结果：列表中不应再出现"nginx"。