Google AI Studio 应用部署后一片空白？原因与解决办法

为什么会这样

应用在 AI Studio 的预览里好好的，说不定本地也跑通了，结果一部署就是空白页或者 404。这基本逃不出四个原因，而且没有一个意味着应用本身坏了。下面从最好查的开始排——动手之前先打开浏览器的开发者控制台，它通常会直接告诉你踩的是哪一个坑。

1. 你部署的是源码，不是构建产物

最常见的原因。AI Studio 给你的是一个项目文件夹，而托管平台要的是构建产物。如果你上传的是 package.json、src/ 文件夹、vite.config.ts 这些东西，托管平台拿到的就是无法直接运行的原始源码，于是页面空白。

解法：先构建项目，再把生成的 dist/ 文件夹——里面的内容，不是整个项目——部署上去。React2Static 会在你浏览器里跑完这个构建，直接给你一个可以上传的 dist/ 文件夹。在 Netlify 或 Cloudflare Pages 上，要拖的是构建出来的那个文件夹，不是整个项目文件夹。

2. 页面空白，JS 和 CSS 文件报 404

看看控制台。如果看到 /assets/index-abc123.js 这类文件报 404，说明页面加载了但脚本没加载成功：应用是从站点根目录去请求文件的，但文件实际托管在别的路径下。这个坑在 GitHub Pages 上特别常见，因为项目站点是从 /your-repo/ 提供的，不是从 / 。

解法：在 vite.config.ts 里把 base 路径设成和应用实际所在位置一致。根域名下是 "/"；GitHub Pages 的项目站点是 "/your-repo/"：

// vite.config.ts
export default defineConfig({
  base: '/your-repo/',
});

改完要重新构建一次。如果你部署在域名根目录，或者 *.pages.dev / *.netlify.app 这样的子域名下，默认的 "/" 本来就是对的——这也是为什么部署到 Cloudflare Pages 或 Netlify 完全不会碰到这个问题。

3. "API key is undefined"，或者 AI 功能完全没反应

应用加载没问题，但凡是调用 Gemini 的功能都失败。这里分两种情况：

托管平台上没配置这个环境变量。 去平台设置里加上——Netlify 在 Site settings 里的 Environment variables，Cloudflare Pages 在 Settings 里的 Environment variables——变量名要跟代码里要求的完全一致，加完重新部署。

变量是配了，但这个密钥本来就不该出现在前端。 打包进前端 JavaScript 的密钥，任何打开网站的人都能看到。如果只是私下的演示项目倒还好；只要是公开的东西，就该把调用 Gemini 的逻辑挪到一个小的 serverless 函数背后（Netlify Functions、Cloudflare Workers 都行），让密钥留在服务器端，永远不会传到浏览器里。

不确定构建出来的东西会不会泄露密钥？React2Static 会在你下载产物之前扫描项目里有没有暴露的密钥并提示你，这样你能在应用上线前发现问题，而不是上线后才发现。

4. 首页能打开，但刷新其他页面就 404

你的应用用的是客户端路由（React Router 之类）。第一次访问没问题，因为一开始就是从 index.html 进来的；但你刷新 /about 时，托管平台会去找一个真实存在的 /about 文件，找不到，就返回 404。

解法：告诉托管平台，遇到不认识的路径就返回 index.html。

Netlify —— 在部署的文件夹里加一个 _redirects 文件：

/*    /index.html   200

Cloudflare Pages —— 默认对不认识的单页应用路由会返回 index.html；如果你这边没生效，加上同样的 _redirects 规则就行。

GitHub Pages —— 没有这种兜底机制。要么把应用改成 hash 路由，要么把 index.html 复制一份改名成 404.html。

小提示：有些 AI Studio 应用本来就自带 HashRouter（网址里带个 #），这样完全不会遇到这个问题。

更保险的做法：先导出成静态文件

这四个坑里有三个其实是同一个根源——上传的是源码而不是正经的构建产物，或者部署的位置和预期的不一样。先构建成静态文件，再把这些文件部署到从根路径提供服务的托管平台上，大部分风险在一开始就被排除了。免费部署 Google AI Studio 应用（不用 Cloud Run）讲的就是这套流程。如果你还没试过，建议先在本地跑一遍，确认没问题再公开。

FAQ

为什么我的 Google AI Studio 应用部署后是空白的？

最常见的原因是上传了源码文件夹而不是构建出来的 dist/ 文件夹，或者构建的 base 路径和实际托管的位置对不上。缺环境变量、单页应用路由问题是另外两个常见原因。

为什么我的 JavaScript 文件报 404？

base 路径和应用实际托管的位置不匹配。根域名下把 vite.config.ts 里的 base 设成 "/"，GitHub Pages 的项目站点设成 "/your-repo/"，然后重新构建。

为什么刷新页面会出现 404？

客户端路由需要托管平台在遇到不认识的路径时兜底返回 index.html。在 Netlify 或 Cloudflare Pages 上加一条 _redirects 规则，或者在 GitHub Pages 上改用 hash 路由。

把 Gemini API 密钥放进部署的应用里安全吗？

不安全——写在前端代码里的密钥，任何打开网站的人都能看到。只要是公开的东西，就该通过 serverless 函数去调用 Gemini，让密钥留在服务器端。