如何在NameCheap cPanel上部署Vite React项目？

一、静态文件托管（推荐方案，无需Node服务） #

Vite构建的React应用是纯静态资源，直接用cPanel的静态文件托管即可，无需创建Node.js应用：

• 本地执行npx vite build生成dist目录，确认目录内包含index.html和assets文件夹
• 登录cPanel，打开文件管理器，进入你的域名根目录（主站为public_html，子域名对应其专属目录）
• 将dist内的所有文件（而非整个dist文件夹）上传至该根目录
• 配置cPanel的错误页面：将404错误页面指向index.html（解决React单页应用的路由 fallback 问题）
• 访问你的域名即可正常加载应用

二、Node.js + Express部署方案（如需后端联动） #

若必须用Node服务托管，需确保server.js配置正确：

正确的server.js代码 #

const express = require('express');
const path = require('path');
const app = express();

// 托管dist目录下的静态资源
app.use(express.static(path.join(__dirname, 'dist')));

// 处理所有路由请求，返回index.html（适配React单页路由）
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'dist', 'index.html'));
});

// 使用cPanel分配的端口，不要硬写固定端口
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

部署步骤 #

• 本地项目根目录执行npm init -y初始化项目，安装依赖：npm install express --save
• 将server.js、package.json、package-lock.json及dist文件夹打包，上传至cPanel的Node.js应用目录（路径示例：/home/你的用户名/nodeapps/你的应用名）
• 在cPanel的Node.js管理界面，设置应用启动文件为server.js
• 点击Run NPM Install安装依赖，随后启动应用
• 配置cPanel的域名映射，将自定义域名指向Node应用的访问地址（cPanel会自动生成应用访问URL，也可绑定自有域名）

三、503错误排查要点 #

• 查看Node应用日志：在cPanel的Node.js管理界面找到日志选项，根据报错信息定位问题（如端口占用、文件路径错误、依赖缺失）
• 校验文件路径：确认server.js中dist的路径是否与实际上传的目录结构匹配，路径错误会导致资源无法读取
• 检查文件权限：cPanel内文件权限需设置为644（文件）、755（文件夹），避免因权限不足导致无法访问
• 对齐Node版本：确保cPanel的Node.js版本与本地开发版本尽量一致，避免版本兼容问题

内容的提问来源于stack exchange，提问作者Hafiz Muhammad Zohair Ajmal