个人业务展示简约静态网站（卡片式）：轻量、好看又好维护的方案

Vite + React 项目部署完整指南（Windows 环境）

项目地址：个人业务展示简约静态网站（卡片式）

本文档总结了 Vite + React 项目从本地构建到服务器部署的全流程，包含常见问题及解决方案，适用于个人业务展示类静态项目部署。

一、环境准备

1. 必备工具安装

  • Node.js（核心依赖，推荐 v14.18+ 版本）

    下载地址：Node.js 官网
    验证安装：打开终端执行以下命令，能显示版本号即安装成功

    1
    2
    node -v  # 示例输出：v20.10.0
    npm -v   # 示例输出：10.2.3

  • pnpm 包管理器（可选，替代 npm，速度更快）
    安装命令：

    1
    2
    npm install -g pnpm  # 通过 npm 全局安装 `pnpm`
    pnpm -v  # 验证安装，示例输出：9.1.0

2. 解决 PowerShell 执行权限问题

Windows 默认限制脚本运行，首次使用需配置执行策略：

  1. 以 管理员身份 打开 PowerShell

  2. 执行命令修改策略：

    1
    Set-ExecutionPolicy RemoteSigned

  3. 输入 Y 确认，关闭窗口后生效（后续可正常执行 npm/pnpm 命令）

二、本地构建步骤

1. 项目文件检查

进入项目根目录（需包含以下核心文件）：

  • package.json：项目依赖和脚本配置
  • vite.config.js 或 vite.config.ts：Vite 构建配置
  • src 文件夹：源代码目录（含 React 组件、页面等）

2. 安装项目依赖

在项目根目录执行以下命令安装依赖：

1
2
3
4
5
# 使用 pnpm（推荐）
pnpm install

# 或使用 npm
npm install
  • 成功后生成 node_modules 文件夹（存放依赖）
  • 若安装失败：
    1. 删除 node_modules 文件夹和 package-lock.json（或 pnpm-lock.yaml）
    2. 重新执行安装命令

3. 配置 Windows 兼容的构建脚本

Windows 不支持 Linux 命令（如 rm cp），需修改 package.json 中的 scripts 字段，确保构建命令兼容：

推荐配置（跨平台兼容）：

1
2
3
4
5
6
7
{
  "scripts": {
    "dev": "vite --host --port 3000",  // 开发环境启动命令
    "build:client": "vite build --outDir dist",  // 核心构建命令（输出到 dist 文件夹）
    "build": "rimraf dist && pnpm build:client"  // 完整构建流程（先清理旧文件，再构建）
  }
}

配置说明：

  1. 安装 rimraf（跨平台删除工具，替代 Linux 的 rm -rf）：

    1
    pnpm add -D rimraf  # 或 npm install rimraf --save-dev

  2. rimraf dist：安全删除旧的 dist 目录（无论目录是否存在都不报错）

  3. vite build --outDir dist：指定构建产物输出到 dist 文件夹

4. 执行构建命令

在项目根目录执行：

1
2
3
4
5
# 使用 pnpm
pnpm build

# 或使用 npm
npm run build
  • 成功标志：终端显示构建完成信息，项目根目录生成 dist 文件夹（含 HTML、CSS、JS 等静态资源）
  • 常见构建失败原因及解决：
    • 提示 vite: command not found：重新安装 Vite（pnpm add -D vite）
    • 提示依赖缺失：检查 package.json 中是否包含 @vitejs/plugin-react 等必要依赖，缺失则安装
    • 配置错误：检查 vite.config.js 是否正确引入 React 插件（示例配置见下方）

附：vite.config.js 基础配置（确保 React 正常构建）

1
2
3
4
5
6
7
// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],  // 必须启用 React 插件
});

5. 本地预览构建结果（可选）

构建完成后，可通过以下命令预览 dist 文件夹的效果：

1
2
# 使用 pnpm
pnpm preview  # 或 npm run preview

终端会提示预览地址（如 http://localhost:4173），打开浏览器访问，确认页面正常显示。

三、部署步骤

1. 部署前准备

  • 确认 dist 文件夹已生成且内容完整（含 index.html 及相关资源）
  • 压缩 dist 文件夹（便于上传）或直接通过 FTP / 文件管理器上传

2. 1Panel 面板部署（静态网站）

  1. 登录 1Panel 面板，进入「网站」模块，点击「创建网站」

  2. 选择「静态网站」类型，填写网站名称和域名（可选）

  3. 上传部署文件：

    • 方式 1：直接上传 dist 文件夹中的所有内容到网站根目录
    • 方式 2：指定本地 dist 路径为「运行目录」

  4. 关键配置（解决 React 路由刷新 404 问题）：

    进入网站「配置」→「Nginx 配置」，添加以下规则：

    1
    2
    3
    location / {
      try_files $uri $uri/ /index.html;  # 所有路由指向 index.html，兼容 SPA 路由
    }

  5. 保存配置，访问域名验证部署结果

3. 其他部署选项

选项 1：静态托管平台（Vercel/Netlify）

  1. 将代码推送到 GitHub/GitLab 仓库
  2. 在 Vercel/Netlify 中导入仓库，自动检测项目类型
  3. 构建配置（默认自动识别，可手动指定）：
    • 构建命令：pnpm build 或 npm run build
    • 输出目录：dist
  4. 部署完成后获取默认域名，支持自定义域名

选项 2：传统服务器（Nginx）

  1. 将 dist 文件夹上传到服务器（如 /var/www/your-site 目录）

  2. 配置 Nginx 站点：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    server {
      listen 80;
      server_name your-domain.com;  # 替换为你的域名
      root /var/www/your-site/dist;  # 指向 dist 目录

      location / {
        try_files $uri $uri/ /index.html;  # 解决 SPA 路由问题
      }
    }

  3. 重启 Nginx 生效：systemctl restart nginx

四、常见问题及解决方案

问题现象 原因 解决方案
'rm' 不是内部或外部命令 构建脚本使用 Linux 命令，Windows 不兼容 1. 安装 rimraf 并替换为 rimraf dist
2. 或使用 Windows 命令 rmdir /s /q dist
ENOENT: no such file or directory 在非项目根目录执行命令，找不到 package.json 执行 cd .. 回到项目根目录（含 package.json 的目录）
依赖安装失败 /node_modules missing 依赖缓存损坏或安装不完整 1. 删除 node_modules 和锁文件
2. 重新执行 pnpm install 或 npm install
构建后刷新页面 404 React Router 单页应用路由特性，服务器未配置 fallback 配置服务器指向 index.html（见部署步骤中的 Nginx 规则）
vite: command not found Vite 未安装或未在依赖中 执行 pnpm add -D vite 或 npm install vite --save-dev

五、总结

  1. 核心流程：环境准备 → 依赖安装 → 配置兼容脚本 → 本地构建 → 服务器部署
  2. 关键注意点：
    • Windows 需使用 rimraf 替代 rm 命令，避免脚本兼容性问题
    • 单页应用必须配置服务器路由 fallback（指向 index.html），解决刷新 404 问题
    • 部署前务必通过 pnpm preview 本地验证构建结果

按此指南操作，可顺利完成 Vite + React 项目的部署。