GitHub开源项目：IT-Tools源码构建部署及其部署排错

环境准备

物理环境：win11专业版/Ubuntu-24.04.2

安装 Node.js（推荐 v20+）和 pnpm（包管理器）。

克隆项目代码：
git clone https://github.com/CorentinTh/it-tools.git
cd it-tools

或者直接从GitHub下载源码
安装依赖
pnpm install

方法 1：使用官方安装脚本（推荐）

这是 pnpm 官方推荐的安装方式，适用于大多数 Linux 系统：

首先确保系统安装了curl（如果没有可以先安装）：
sudo apt update && sudo apt install -y curl

运行 pnpm 官方安装脚本：
curl -fsSL https://get.pnpm.io/install.sh | sh -

安装完成后，需要让系统识别 pnpm 命令，执行以下命令刷新环境变量：
source ~/.bashrc # 如果你用的是bash
# 或者如果是zsh：
# source ~/.zshrc

方法 2：通过 npm 安装（如果已安装 npm）

如果你已经安装了 npm（Node.js 的包管理器），也可以通过 npm 安装 pnpm：

先安装 npm（如果未安装）：
sudo apt update && sudo apt install -y npm

用 npm 全局安装 pnpm：
sudo npm install -g pnpm

验证安装

安装完成后，运行以下命令确认 pnpm 已正确安装：
pnpm --version

如果输出版本号，说明安装成功，之后就可以正常运行pnpm install命令了。

构建生产版本
pnpm build

部署静态文件

步骤1.安装 Nginx（若未安装）

根据系统类型执行命令：

Ubuntu/Debian：
sudo apt update && sudo apt install nginx

CentOS/RHEL：
sudo yum install epel-release # CentOS需先装EPEL源
sudo yum install nginx

安装后启动服务并设为开机自启：
sudo systemctl start nginx
sudo systemctl enable nginx

步骤2.复制 dist 目录到 Nginx 站点目录

确定 Nginx 站点根目录：

Nginx 默认站点目录为：

Ubuntu/Debian：/var/www/html

CentOS/RHEL：/usr/share/nginx/html

也可通过查看 Nginx 配置文件（如 /etc/nginx/sites-available/default）确认 root 字段。

创建项目部署目录（以部署到 /var/www/html/it-tools 为例）：
sudo mkdir -p /var/www/html/it-tools

复制 dist 文件：

假设你的 dist 目录在项目根目录（如 ~/it-tools/dist），执行：
sudo cp -r ~/it-tools/dist/* /var/www/html/it-tools/

小tips：从GitHub直接下载项目源码时目录名是it-tools-main，建议重命名为it-tools，方便跟随步骤操作

步骤3.配置 Nginx 站点规则

创建 Nginx 配置文件：
sudo nano /etc/nginx/conf.d/it-tools.conf

写入基础配置（适配单页应用路由，避免刷新 404）：
点击查看代码

复制代码

server {
    listen 80;                 # 监听80端口（HTTP）
    server_name localhost;    # 改为你的域名/IP，如 example.com 或 192.168.1.100

    root /var/www/html/it-tools;  # 指向部署目录
    index index.html;

    # 处理单页应用路由（必配！否则刷新页面会404）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 可选：优化静态文件缓存（如JS/CSS/图片）
    location /static/ {
        expires 30d;          # 缓存30天
        add_header Cache-Control "public";
    }
}

代码中的`server_name`：若需通过域名访问，需替换为实际域名（需提前解析到服务器 IP）；若仅本地测试，保持 localhost 即可。

步骤4.验证配置并重启 Nginx

检查配置语法：
sudo nginx -t

若输出 nginx: configuration file /etc/nginx/nginx.conf test is successful，则配置无误。

重启 Nginx 生效：
sudo systemctl restart nginx

步骤5.测试访问

打开浏览器，访问：

若 server_name 为 localhost：http://localhost

若为服务器 IP（如 192.168.1.100）：http://192.168.1.100

若为域名：http://your-domain.com

若页面正常加载、跳转和刷新无 404，则部署成功。

end.常见问题处理

页面空白或资源加载失败：

检查 dist 目录是否正确复制（文件是否完整，权限是否为 Nginx 运行用户可读取）。

Nginx 运行用户：Ubuntu 是 www-data，CentOS 是 nginx。修复权限：
sudo chown -R www-data:www-data /var/www/html/it-tools # Ubuntu
sudo chown -R nginx:nginx /var/www/html/it-tools # CentOS

CentOS 下访问被拒绝（SELinux 限制）：

执行以下命令开放权限：
sudo setsebool -P httpd_can_network_connect on # 允许网络访问
sudo chcon -Rv --type=httpd_sys_content_t /var/www/html/it-tools # 设置SELinux上下文

防火墙拦截端口：

开放 80 端口（HTTP）：

ufw（Ubuntu）：sudo ufw allow 80

firewalld（CentOS）：sudo firewall-cmd --permanent --add-service=http && sudo firewall-cmd --reload

如需 HTTPS 部署（更安全），可额外配置 Let's Encrypt 证书（通过 certbot 工具），流程可参考https://certbot.eff.org/instructions?ws=nginx&os=ubuntufocal

如果访问网站是 Nginx 默认欢迎页，说明项目静态文件未正确部署

先检查部署目录文件：
ls /var/www/html/it-tools # 确认有index.html等dist文件

若无需重新部署

修复权限（若文件存在但无法访问）：
sudo chown -R www-data:www-data /var/www/html/it-tools # Ubuntu/Debian
# sudo chown -R nginx:nginx /var/www/html/it-tools # CentOS/RHEL

执行完上述代码后，按以下顺序排查：

检查 Nginx 配置优先级

查看已启用的站点（若存在default链接，会覆盖新配置）
ls /etc/nginx/sites-enabled/

若有 default，删除它：（默认是有的）
sudo rm /etc/nginx/sites-enabled/default

确认部署目录文件
ls /var/www/html/it-tools # 必须包含 index.html 等 dist 构建文件
重启 + 强制刷新浏览器
sudo nginx -t && sudo systemctl restart nginx

浏览器按 Ctrl+F5 强制刷新，或换浏览器访问。

若仍无效，补充执行：

查看 Nginx 实际加载的配置（确认 it-tools.conf 已生效）
sudo nginx -T | grep -i it-tools

成功部署页面如下

如有其他问题请在评论区留言