Nginx部署前端静态文件指南分享(基于虚拟机环境)_Oracle

掌握 用nginx部署任意前端静态文件 是后端/运维入门的核心技能之一。无论是下载的模板（如adminlte）、前端框架打包后的文件（vue/react的dist目录），还是简单的html页面，都能通过这套流程快速在网页上展示。

本笔记以虚拟机 为环境，从文件传输到nginx配置，全程实操落地，让你 拿到前端文件就能部署！

1 准备工作

1.1 环境要求

虚拟机：已安装nginx（若未安装，执行sudo apt install nginx -y）
物理机：存有前端文件（如adminlte-3.2.0，或任意包含index.html的文件夹）
工具：vs code + ssh remote扩展（用于远程连接虚拟机并传输文件）

1.2 目标

将物理机的前端文件传到虚拟机，通过nginx配置，让浏览器访问http://虚拟机ip:端口时能正常显示前端内容。

2 在虚拟机中创建工程目录

在 vs code 的远程终端（左下角显示 ssh: vm-via-nat 时，按 ctrl + ~ 打开终端）执行：

#在家目录新建文件夹，名字my-project
mkdir ~/my-project

为了避免权限问题且便于管理，在用户的目录下创建专用文件夹，按配置文件和前端文件分类存放：

# 登录虚拟机后，在终端执行（如用户为kr，路径默认在/home/kr）
mkdir -p ~/my-project/config  # 存放nginx自定义配置文件（按端口/功能分类）
mkdir -p ~/my-project//www    # 存放前端静态文件（如adminlte、dist等）

在 linux 中，~ 是一个特殊符号，代表当前用户的主目录，即 /home/用户名。

~/my-project//config：后续所有项目的nginx配置文件都放这里。
~/my-project//www：前端文件的根目录，每个项目单独建子文件夹（如~/my-project//www/adminlte放adminlte文件）。

3 将物理机前端文件传到虚拟机

用vs code + ssh远程连接虚拟机，通过拖放传输文件，这是最直观的方式：

在vs code左侧资源管理器中，导航到虚拟机的/home/kerui/my-project//www目录；
打开物理机的文件管理器，找到前端文件；
直接将物理机的前端文件夹拖到vs code的/home/kerui/my-project//www目录中；
等待传输完成，此时虚拟机中会出现/home/kerui/my-project//www/adminlte-3.2.0。

当然，你也可以选择从主机终端输出以下命令进行传输：

scp -p [d端口号] -r [物理机文件路径] [虚拟机文件路径]

具体可见下面图片页面所示。

传输后在该页面可以看到你新过来的文件，你也可以在这里任意新建文件夹跟其他文件，因为是你的家目录，不会报权限错误。

4 编写nginx配置文件

为前端文件创建专属配置，指定访问端口和文件路径：

4.1 新建配置文件

在虚拟机终端执行，创建并编辑配置文件（以部署adminlte到8080端口为例）：

# 进入配置文件目录
cd ~/my-project/config  
# 新建配置文件（文件名建议包含端口或项目名，如adminlte-8080.conf）
vim adminlte-8080.conf

这是一种方法，但是我更推荐以下方法，在vscode左侧新建文件，作用一样。

4.2 配置文件内容

程序如下：

server {
    listen 8080;  # 访问端口（可自定义，如8081、8090）
    server_name _;  # 本地测试用“_”表示任意域名

    # 前端文件在虚拟机中的路径（必须是绝对路径）
    root /home/kerui/my-project/www/adminlte-3.2.0;  
    # 默认首页（前端文件夹中必须有index.html）
    index index.html index.htm;

    # 解决单页应用路由问题
    location / {
        try_files $uri $uri/ /index.html;
    }
}

但到这里还没有结束，因为nginx默认只加载系统目录的配置，所以在你配置之前，系统并不会去读你创建的文件目录，具体见下一节。

5 让nginx加载自定义配置

nginx默认只加载系统目录的配置，需手动让它识别我们在~/my-project/config中的文件：

5.1 编辑nginx主配置

执行以下命令打开nginx主配置文件（需要sudo权限，仅需配置一次）：

sudo vim /etc/nginx/nginx.conf

5.2 添加自定义配置目录

在http块末尾添加一行，让nginx加载~/my-project/config下的所有.conf文件：

http {
    ...  # 原有的其他配置（保留不动）

    # 保留默认的系统配置目录（不影响原有服务）
    include /etc/nginx/conf.d/*.conf;
    # 新增：加载kerui用户的自定义配置目录（关键！）
    include /home/kerui/nginx/config/*.conf;
}

按esc，输入:wq保存退出。

这里最后的*.conf则是系统会自动找寻该文件夹下的所有conf文件，所以后续你只要在该路径下创建conf文件都不需要再跑到系统目录下更改，就会更加简单便捷。

6 验证配置并启动服务

6.1 检查配置语法

执行以下命令，确保配置文件无错误（若报错，按提示修改路径或语法）：

sudo nginx -t

成功提示：

nginx: configuration file /etc/nginx/nginx.conf test is successful

6.2 重启nginx生效

sudo systemctl restart nginx

也可以选择使用：

sudo nginx -s reload

这一个主要区别是可以不断网就重新生效，对于你一些正在挂着的网页有效果。

6.3 浏览器访问测试

查看虚拟机ip（终端执行ip addr，如192.168.56.10）。
物理机浏览器输入：http://192.168.56.10:8080（ip替换为你的虚拟机ip，端口对应配置文件的8080）。
若显示前端页面（如adminlte的首页），则部署成功。

7 查看nginx日志（通用查错方法）

当遇到问题或其他未知错误时，优先查看nginx的日志文件，里面会记录详细的错误原因（如权限拒绝、路径不存在、配置语法错误等）。

7.1 日志文件的默认路径

nginx的日志通常存放在 /var/log/nginx/ 目录下，核心有两个文件：

错误日志：/var/log/nginx/error.log（记录启动失败、访问错误等关键信息，最常用）。
访问日志：/var/log/nginx/access.log（记录所有浏览器的访问记录，用于分析访问情况）。

7.2 查看错误日志的命令

在虚拟机终端执行以下命令，实时查看错误日志（方便调试时追踪问题）：

# 实时输出最新的错误日志（按ctrl+c退出）
sudo tail -f /var/log/nginx/error.log

如果需要查看历史错误，可直接打开日志文件：

# 用vs code打开日志文件（可视化查看，支持搜索）
code /var/log/nginx/error.log  # 需要先通过ssh连接虚拟机，且vs code已远程连接

7.3 常见日志信息及对应解决方法

错误日志内容示例	可能的问题	解决思路（对应前面的方法）
permission denied: /home/kerui/...	权限不足	执行 chmod -r 755 目标路径
no such file or directory: /home/kerui/...	路径错误或文件不存在	检查配置文件中root路径是否正确
address already in use: 0.0.0.0:8080	端口被占用	更换端口（如8081）并重启nginx
connect() failed (111: connection refused)	后端服务未启动（反向代理时）	启动后端服务，确保端口正确