如何在 Windows VPS 上安装 React.js：完整设置指南

React.js 是由 Meta（前身为 Facebook）维护的开源 JavaScript 库，用于构建基于组件的用户界面，特别是无需完整页面重载即可动态更新 DOM 的单页应用程序（SPA）。在 Windows VPS 上安装 React（而非本地工作站）可为您提供持久、可远程访问的开发环境，并配备专用资源，非常适合团队协作、CI/CD 流水线和预发布部署。

本指南涵盖在 Windows VPS 上进行生产级 React.js 安装的每个步骤：从 Node.js 运行时配置和环境变量管理，到项目脚手架搭建、开发服务器运行和生产构建输出。同时还涵盖了那些遵循表面教程的工程师常遇到的非显而易见的故障模式。

为何在 Windows VPS 上安装 React 而非本地主机

在 VPS 托管实例上运行 React 开发环境（而非本地机器）可解决多个实际问题：

• 持续运行时间：即使本地机器关闭，开发服务器仍保持运行，允许远程团队成员或 QA 测试人员随时访问实时预览 URL。
• 一致的环境：每位开发者连接到相同的操作系统、Node 版本和依赖树，消除”在我机器上能运行”的问题。
• 资源隔离：CPU 密集型构建（npm run build、大型 Webpack 编译）不会降低本地工作站的性能。
• 预发布环境一致性：当生产环境也基于 Windows Server（IIS、ASP.NET 混合架构）时，Windows VPS 可镜像目标部署环境。
• 远程可访问性：您可以在特定端口上公开开发服务器，并从任何地方的任何浏览器访问它。

如果您的工作负载最终扩展到需要在 Node.js API 旁边提供已编译的 React 资源，请考虑迁移到独立服务器环境，以获得有保障的 I/O 吞吐量并避免邻居干扰效应。

前提条件

开始之前，请确认您的 Windows VPS 上已满足以下条件：

• Windows Server 2016 / 2019 / 2022 或 Windows 10/11（64 位）
• 通过 RDP 进行管理员或提升权限的用户访问
• VPS 上的出站互联网访问（用于下载安装程序和 npm 包）
• 至少 2 GB RAM — Webpack 的内存编译非常耗内存；对于依赖项较多的项目，建议使用 4 GB
• 文本编辑器或 IDE — Visual Studio Code 是 React 开发的事实标准

步骤 1：在 Windows 上安装 Node.js

1.1 下载 LTS 版本

React 不需要最新版本的 Node.js。LTS（长期支持）版本是任何注重稳定性的环境的正确选择。

1. 在您的 VPS 上打开浏览器（或远程下载后通过 RDP 剪贴板传输）。
2. 访问 https://nodejs.org。
3. 下载当前 LTS 版本（例如 20.x 或 22.x）的 Windows 安装程序（.msi）。

重要提示：始终下载 64 位 .msi 安装程序，而非 .zip 压缩包。.msi 会自动处理 PATH 注册、服务集成和 Visual C++ 可再发行组件依赖项。.zip 压缩包需要手动配置 PATH，是导致 npm 无法识别错误的常见原因。

1.2 运行安装程序

执行下载的 .msi 文件并按照向导操作：

1. 接受许可协议。
2. 除非有特殊原因，否则将目标路径保留为默认值（C:Program Filesnodejs）。
3. 在自定义设置界面，确保勾选以下所有组件：

• Node.js 运行时
• npm 包管理器
• 添加到 PATH（这是最重要的复选框——如果未勾选，任何终端都无法识别 node 或 npm）
• 在线文档快捷方式（可选）

1. 在原生模块工具界面，如果您预计使用任何需要原生编译的 npm 包（node-gyp、bcrypt、sharp 等），请勾选“自动安装必要工具”。这将静默安装 Chocolatey、Python 和 Visual Studio 构建工具。
2. 完成安装并重启终端会话（如果 PATH 更改未立即生效，则重启整个 RDP 会话）。

1.3 验证安装

打开新的 PowerShell 或命令提示符窗口（不要使用安装前已打开的窗口——它不会包含更新后的 PATH）并运行：

node -v

npm -v

两个命令都必须返回版本字符串。如果任一命令返回 'node' is not recognized as an internal or external command，则表示 PATH 未正确设置。请参阅下面的故障排除部分。

预期输出示例：

v20.14.0
10.7.0

1.4 配置 npm 的全局包目录（可选但推荐）

默认情况下，npm 将全局包安装到 C:Users<username>AppDataRoamingnpm。在共享或多用户 Windows Server 环境中，这可能导致权限冲突。要设置自定义全局目录：

npm config set prefix "C:npm-global"

然后通过系统属性 > 环境变量 > 系统变量 > Path 将 C:npm-global 添加到系统 PATH。

步骤 2：搭建 React 应用程序脚手架

2.1 现代方法：Vite（推荐替代 Create React App）

原文推荐使用 create-react-app（CRA）。这是过时的建议。CRA 于 2023 年初正式弃用，不再由 React 核心团队维护。React 文档本身也不再为新项目推荐它。

当前推荐的脚手架工具为：

对于 Windows VPS 上的简单 SPA，Vite 是 2024 年及以后的正确选择。

2.2 使用 Vite 创建新的 React 项目

打开 PowerShell 并导航到您的项目目录：

cd C:Projects

搭建新的 React 项目脚手架：

npm create vite@latest my-react-app -- --template react

使用 TypeScript（对于任何非简单项目强烈推荐）：

npm create vite@latest my-react-app -- --template react-ts

导航到项目目录并安装依赖项：

cd my-react-app
npm install

2.3 如果必须使用 Create React App（遗留项目）

如果您正在维护需要 CRA 的遗留代码库，请使用 npx 运行它，无需全局安装：

npx create-react-app my-react-app

不要运行 npm install -g create-react-app。全局安装方式已弃用，会拉取过时的缓存版本。使用 npx 始终从注册表获取最新可用版本。

步骤 3：运行开发服务器

3.1 启动开发服务器

对于基于 Vite 的项目：

npm run dev

对于基于 CRA 的项目：

npm start

两个命令都会启动本地开发服务器。Vite 默认使用 http://localhost:5173；CRA 默认使用 http://localhost:3000。

3.2 在 Windows VPS 上公开开发服务器（远程访问）

在本地机器上，开发服务器只能从 localhost 访问。在 VPS 上，您通常希望通过互联网从本地浏览器访问它。需要进行两项更改：

将服务器绑定到所有网络接口：

对于 Vite，编辑 vite.config.js（或 vite.config.ts）：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: 5173,
  },
})

对于 CRA，在启动前设置 HOST 环境变量：

set HOST=0.0.0.0
npm start

在 Windows 防火墙中开放端口：

netsh advfirewall firewall add rule name="React Dev Server" dir=in action=allow protocol=TCP localport=5173

完成后，您可以从任何浏览器通过 http://<your-vps-ip>:5173 访问开发服务器。

安全警告：切勿在生产 VPS 上将开发服务器未经身份验证地暴露在公共互联网上。对于任何处理真实数据的环境，请使用反向代理（Nginx 或带 URL 重写的 IIS）或 VPN 隧道。

步骤 4：项目结构和关键文件

了解脚手架结构可防止您在修改文件时产生困惑：

my-react-app/
├── public/             # Static assets served as-is (favicon, robots.txt)
├── src/
│   ├── assets/         # Images, fonts imported by components
│   ├── App.jsx         # Root component
│   ├── App.css         # Root component styles
│   ├── main.jsx        # Entry point — mounts <App /> into index.html
│   └── index.css       # Global styles
├── index.html          # HTML shell — Vite injects the bundle here
├── vite.config.js      # Vite configuration
├── package.json        # Dependencies and scripts
└── node_modules/       # Installed packages (never commit this)

src/main.jsx 文件是应用程序入口点。它调用 ReactDOM.createRoot() 将根组件挂载到 index.html 中的 #root div 中。您构建的每个组件最终都将被导入到这个树中。

步骤 5：构建生产版本

当应用程序准备好部署时，生成优化的静态构建：

npm run build

此命令调用 Vite 基于 Rollup 的打包器（或 CRA 的 Webpack），它将：

• 将 JSX 和现代 JavaScript 转译为浏览器兼容的 ES5/ES2015+
• 从打包中摇树删除未使用的代码
• 压缩 JavaScript、CSS 和 HTML
• 生成带内容哈希的文件名以实现长期浏览器缓存
• 将所有内容输出到 dist/ 目录（Vite）或 build/ 目录（CRA）

在部署前本地预览生产构建：

npm run preview

dist/ 的内容是纯静态文件（HTML、JS、CSS、资源）。它们可以由任何 Web 服务器提供——Windows Server 上的 IIS、Nginx、Apache 或静态托管服务。

将构建部署到 Windows Server 上的 IIS

如果您的 VPS 运行 IIS，请配置一个指向 dist/ 文件夹的新站点。由于 React SPA 使用客户端路由，您必须添加 URL 重写规则，将所有 404 重定向回 index.html：

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="React SPA" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/index.html" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

没有此规则，直接导航到 /dashboard 等路由时，IIS 将返回 404，而不是加载 React 应用。

如果您在后端 API 旁边提供 React 前端，并需要托管控制面板环境，带 cPanel 的 VPS 可以简化虚拟主机配置和 SSL 终止。

步骤 6：使用 HTTPS 保护应用程序

生产 React 应用必须通过 HTTPS 提供服务。浏览器会阻止混合内容请求，许多浏览器 API（Service Worker、地理位置、剪贴板）仅限于安全上下文。

对于 VPS 托管的部署：

1. 为您的域名获取 SSL 证书。AlexHost 提供可直接安装在您 VPS 上的 SSL 证书。
2. 配置 IIS 或您的反向代理，在 443 端口终止 TLS，并将 HTTP（80 端口）重定向到 HTTPS。
3. 如果使用 CRA 内置服务器进行本地 HTTPS 测试，请将 HTTPS 环境变量设置为 true。

如果您尚未将域名指向 VPS，请先通过域名注册注册一个，并配置 DNS A 记录指向您的 VPS IP 地址。

步骤 7：常见问题故障排除

node 或 npm 无法识别

这意味着 Node.js 安装目录不在系统 PATH 中。手动修复：

1. 按 Win + R，输入 sysdm.cpl，按回车。
2. 转到高级 > 环境变量。
3. 在系统变量下，找到 Path 并点击编辑。
4. 将 C:Program Filesnodejs 添加为新条目。
5. 点击所有对话框上的确定，然后打开新的终端窗口。

npm 安装期间出现 EACCES 或权限拒绝错误

在 Windows Server 上，这通常发生在以受限用户身份运行 npm 时。要么以管理员身份运行 PowerShell，要么将 npm 的缓存和全局目录配置为当前用户拥有的路径：

npm config set cache "C:npm-cache"
npm config set prefix "C:npm-global"

端口已被占用

如果端口 5173 或 3000 被其他进程占用：

netstat -ano | findstr :5173

在最后一列中识别 PID，然后：

taskkill /PID <PID> /F

或者，在 vite.config.js 中更改端口，或将 --port 作为标志传递：

npm run dev -- --port 3001

npm ERR! code EINTEGRITY（校验和不匹配）

这表示 npm 缓存已损坏。清除缓存并重试：

npm cache clean --force
npm install

首次运行时 npm install 速度缓慢

React 项目的初始依赖项安装可能需要 2–5 分钟，具体取决于 VPS 网络吞吐量和磁盘 I/O。如果持续超时，请检查 VPS 是否可以通过 443 端口出站访问 registry.npmjs.org。某些数据中心防火墙策略默认会阻止此访问。

决策矩阵：为您的 VPS 选择合适的 React 设置

实用关键要点清单

• 使用 .msi 安装程序（而非 .zip 压缩包）安装 Node.js 的 LTS 版本，以确保自动 PATH 注册。
• 对所有新 React 项目使用 npx create vite@latest — CRA 已弃用，不应用于全新开发。
• 在 VPS 上，在 vite.config.js 中设置 host: '0.0.0.0'，并在 Windows 防火墙中开放相应端口，以便远程访问开发服务器。
• 添加 IIS URL 重写规则，将所有非文件、非目录请求重定向到 index.html — 没有此规则，直接 URL 访问时客户端路由将失效。
• 始终通过 HTTPS 提供生产构建；在上线前获取并安装 SSL 证书。
• 运行 npm run build 并在部署前检查 dist/ 输出——使用 npm run build -- --report 或 vite-bundle-visualizer 检查打包大小。
• 切勿将 node_modules/ 提交到版本控制；始终将其添加到 .gitignore。
• 如果不同项目需要多个 Node 版本，请安装 nvm-windows 来管理它们，无需全局重新安装 Node.js。

常见问题

React.js 需要在服务器上”安装”，还是只需要构建输出？

React 本身是一个构建时依赖项。npm run build 的生产输出是纯 HTML、CSS 和 JavaScript——服务器上不需要 Node.js 运行时来提供服务。Node.js 只需要在运行构建过程的机器上安装。

npm run dev 和 npm run build 有什么区别？

npm run dev 启动带有热模块替换（HMR）和未压缩源映射的开发服务器——它未针对性能进行优化，绝不应用于提供生产流量。npm run build 生成经过压缩、摇树优化、带内容哈希的静态打包，用于部署。

为什么 Create React App 被弃用，我应该使用什么替代品？

CRA 依赖 Webpack 4，与 Vite 的 ESM 原生开发服务器相比，构建和 HMR 速度明显更慢。React 团队于 2023 年正式从文档中移除了 CRA，现在推荐 SPA 使用 Vite，全栈应用使用 Next.js，数据密集型应用使用 Remix。

我可以在同一个 Windows VPS 上同时运行多个 React 项目吗？

可以。每个项目在不同端口上运行其开发服务器。在每个项目的 vite.config.js 中配置唯一的 port 值，在 Windows 防火墙中开放每个端口，并可选择将 IIS 设置为反向代理，将子域或路径路由到相应端口。

关闭 RDP 会话后如何保持 React 开发服务器运行？

使用进程管理器。全局安装 PM2（npm install -g pm2）并将开发服务器作为托管进程启动：pm2 start npm --name "react-dev" -- run dev。PM2 使进程独立于终端会话持续运行，并可配置为在系统重启时自动重启。