AI 建站与网站上线
AI 生成的 React 网站怎么上线(2026):Vercel 部署、环境变量与白屏排查
拿到 AI 生成的 React + Vite 源码后,如何通过 GitHub 和 Vercel 发布成正式网址?本文讲清项目识别、构建设置、环境变量、内页刷新 404、白屏和图片丢失的检查步骤。

AI 给了你一个 React 项目,预览能打开,下载后却是一堆 .tsx、src 和 package.json。这类文件需要先构建,再部署。本文用 React + Vite 的前端单页应用演示:把源码放进 GitHub,让 Vercel 构建并生成正式网址,再检查白屏、图片丢失和刷新 404。
完成后应该拿到一个别人能直接访问的 HTTPS 地址,首页、内页和图片都能打开。这里提供的是按官方文档整理的操作方案;界面和平台条件核对于 2026 年 11 月 20 日。
打开 package.json,找 scripts 和依赖。普通 Vite 项目常见以下脚本;已有项目可能在构建前多跑 TypeScript 检查,保留它原来的有效配置。
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
}
}
| 你拿到的内容 | 适合怎么处理 |
|---|---|
package.json 包含 Vite,配有 src、index.html | 按本文部署前端单页应用 |
| 只有可直接运行的 HTML、CSS、图片 | 看静态 HTML 免费上线教程 |
有 next、next build、next.config | 采用 Next.js 的框架配置,保留其默认输出设置 |
| 只有一个 React 组件,缺少入口和依赖 | 让 AI 补成完整可构建项目,再发布 |
| 还包含独立后端、数据库或 SSR 服务 | 分别确认服务的部署方案,不能只上传前端 |
不要因为文件夹里有 index.html,就直接把全部源码当静态文件上传。浏览器需要的是构建后的 JavaScript 和资源。Vite 静态部署说明介绍了构建产物与本地预览的区别。
在 GitHub 新建仓库。可以使用私有仓库,再通过 Vercel 的 GitHub 集成授予对应仓库访问权限。AI 工具支持同步 GitHub 的,先同步;只有 ZIP 的,解压后用 GitHub 网页的文件上传入口,或本地 Git 客户端提交项目。
保留 package.json、源码、实际用到的图片、配置和对应包管理器的锁文件。npm 项目通常使用 package-lock.json;原项目若使用 pnpm 或 Yarn,保留其包管理器与锁文件。不要上传 node_modules,也不要提交装着密钥的 .env 文件。
提交后在仓库里点开 src 和图片目录,确认文件确实存在。若仓库最外层套了一个 my-site 文件夹,也可以部署,但稍后要把 Root Directory 选到它。不要把压缩包本身当作源码上传后就开始导入。
如果本机已经能运行项目,可以在项目目录先执行:
npm run build
npm run preview
这组命令以 npm 项目且依赖已安装为前提。构建成功后检查本地预览的首页和图片,再开始云端部署。vite preview 只用来本地验收构建结果,不作为正式服务运行。没有本地环境,也可以直接查看下一步的云端构建日志。
登录 Vercel,打开新建项目入口,选择导入 Git 仓库,连接 GitHub 后找到刚才的仓库。先检查配置,再点 Deploy。Vercel 入门说明可用于核对当前导入入口。
| 配置 | 普通 React + Vite 项目的检查方法 |
|---|---|
| Framework Preset | 应识别为 Vite;识别错误时先确认选中的目录 |
| Root Directory | 选择包含本项目 package.json 的目录,通常是仓库根目录 |
| Build Command | 常见为 npm run build,以项目脚本和包管理器为准 |
| Output Directory | 默认 dist;改过 build.outDir 时填写实际输出目录 |
src 是源码,public 是一部分静态资源,它们通常都不是这个项目的最终输出目录。也不要把 npm run dev 填成构建命令:开发服务会持续运行,无法代替生成部署文件。构建配置文档说明了这些字段的作用。
部署失败时打开 Build Logs,找最早的相关错误。缺模块就查对应依赖和导入路径;Missing script: build 就查项目目录与脚本;输出目录不存在就对照构建日志。把该错误及前后几行交给 AI,修复后提交到同一仓库,跟进新部署。
纯展示页可能不需要环境变量。需要调用后台时,到项目 Settings 的 Environment Variables 添加变量,选中实际部署使用的环境。首次导入新项目应核对 Production 所需的值;后续分支预览再单独配置 Preview。Vercel 环境说明说明了首次部署和后续预览的区别。
例如,前端需要公开的后台地址:
VITE_API_BASE_URL=https://api.example.com
代码里按相同名称读取:
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
这里的域名是占位示例,需要换成真实 HTTPS 接口地址。VITE_ 变量会进入浏览器构建产物,不能存模型 API 私钥、数据库密码或管理员令牌。这些凭据应放在实际实现了权限检查的后端或服务端函数中。只把变量改个名字,也不会自动给前端增加后端能力。Vite 环境变量文档
修改变量后,要重新部署并等待新构建完成。已有部署不会自动换成新值。Vercel 环境变量说明明确了这一点。
如果 Network 面板显示请求还在访问 localhost:8000,访客浏览器正在连接访客自己的电脑。应改成已部署的接口地址,并检查后端是否允许正式网站的来源。表单和登录还要单独验收,可接着看AI 网站的表单、登录与后台。
假设网站支持 /about:从首页点过去正常,把这个地址复制到新标签页却报 404。这通常是浏览器路由和服务器文件路径没有对应上。
对本文这种纯前端 Vite 单页应用,可在项目根目录,也就是与部署用 package.json 同级的位置,添加 vercel.json:
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
]
}
提交并重新部署,再直接打开 /about、刷新一次。这个配置让服务器把前端页面请求交给入口文件,页面最终显示什么仍由前端路由决定。Vercel 的 Vite 单页应用说明
这份示例按未启用 cleanUrls、没有自定义 API 路由的纯前端项目编写。已有 vercel.json 时合并配置,不要覆盖原规则;存在 /api、外部代理、SSR 或框架路由时,先按项目结构处理路由优先级。也别拿这个兜底掩盖丢失的 .js 文件。
正式地址出现白屏时,在浏览器开发者工具打开 Console 和 Network,再刷新。记录第一个报错以及失败请求的地址、状态码和 Content-Type。
| 现象 | 下一步检查 |
|---|---|
.js 请求 404,或返回 text/html | 构建产物、资源路径、Vite 的 base 和重写规则 |
| 只有一张图 404 | 文件是否已提交,路径和文件名大小写是否一致 |
| 首页 200,Console 有运行错误 | 按报错文件检查组件与配置,HTTP 200 不代表页面执行正常 |
| 页面能打开,提交后没有记录 | 检查真实接口、请求响应和接收端保存结果 |
| 访问网址要求登录 Vercel | 核对是否分享了预览地址,以及项目的访问保护范围 |
Vite 的 public/cover.png 通常用 /cover.png 引用;放在 src 中的资源可按项目代码导入,交给构建工具处理。项目部署到域名根目录时,还要检查是否残留了以前子目录部署使用的 base。Vite 静态资源说明
从项目后台复制正式域名,用未登录的浏览器打开。依次检查首页、一个真实内页、内页刷新、手机显示和关键按钮。有表单的,发送一条测试记录,到接收端确认;有登录的,检查回调域名是否包含正式地址。
平台套餐的适用用途和额度以当前方案说明为准。面向国内访客时,再用目标地区的实际网络验收页面和外部资源的可达性,不能用自己的预览结果代替。
以后更新源码,提交到项目配置的生产分支,等对应生产部署完成,再验收同一组操作。若新版本出错,可按发布检查与版本回滚教程处理。正式地址通过这轮检查后,再绑定自己的域名或放进简历、产品介绍页。