Pourquoi votre app Google AI Studio affiche une page blanche après déploiement (et comment la réparer)

Pourquoi ça arrive

Votre app marchait dans la prévisualisation AI Studio, peut-être même en local, et puis vous l'avez déployée et vous tombez sur une page blanche ou un 404. C'est presque toujours l'une de ces quatre causes, et aucune ne veut forcément dire que l'app est cassée. Les voici, en commençant par la plus rapide à vérifier — ouvrez la console développeur de votre navigateur avant de commencer, elle indique souvent laquelle vous concerne.

1. Vous avez déployé la source, pas le build

La cause la plus fréquente. AI Studio vous donne un dossier de projet ; un hébergeur, lui, a besoin du résultat du build. Si vous avez envoyé package.json, un dossier src/ et vite.config.ts, l'hébergeur sert du code source brut, que le navigateur ne sait pas exécuter tel quel, d'où la page blanche.

Solution : générez d'abord le build du projet, puis déployez le dossier dist/ obtenu — son contenu, pas le projet entier. React2Static fait tourner ce build dans votre navigateur et vous donne le dossier dist/ prêt à déposer. Sur Netlify ou Cloudflare Pages, glissez le dossier généré par le build, jamais le dossier du projet.

2. Page blanche avec des 404 sur les fichiers JS et CSS

Ouvrez la console. Si vous voyez des 404 pour des fichiers comme /assets/index-abc123.js, la page HTML s'est chargée, mais pas les scripts : l'app demande ses fichiers depuis la racine du site, alors qu'ils sont hébergés ailleurs. C'est le piège classique sur GitHub Pages, où un site de projet est servi depuis /your-repo/ au lieu de /.

Solution : réglez le base path dans vite.config.ts pour qu'il corresponde à l'URL où l'app est servie. Pour un domaine racine c'est "/" ; pour un site de projet GitHub Pages c'est "/your-repo/" :

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

Relancez le build après l'avoir changé. Si vous hébergez à la racine d'un domaine ou sur un sous-domaine *.pages.dev / *.netlify.app, le "/" par défaut est déjà le bon — c'est pour ça que ce problème disparaît souvent sur Cloudflare Pages ou Netlify.

3. « API key is undefined » ou les fonctionnalités IA ne répondent pas

L'app se charge, mais tout ce qui appelle Gemini échoue. Deux cas de figure :

La variable d'environnement n'est pas définie chez l'hébergeur. Ajoutez-la dans les réglages de l'hébergeur — sur Netlify sous Site settings puis Environment variables, sur Cloudflare Pages sous Settings puis Environment variables — avec le nom exact attendu par le code, puis redéployez.

La variable est définie, mais sa valeur est un secret qui ne devrait pas se retrouver en production. Une clé embarquée dans le JavaScript front-end est lisible par quiconque ouvre le site. Pour une démo privée, ça peut éventuellement passer ; pour tout ce qui est public, placez l'appel à Gemini derrière une petite fonction serverless (Netlify Functions, Cloudflare Workers) pour que la clé reste côté serveur et n'atteigne jamais le navigateur.

Vous voulez vérifier que votre build ne va pas exposer une clé ? React2Static scanne le projet à la recherche de secrets exposés avant le téléchargement et vous les signale, pour que vous le sachiez avant la mise en ligne, et non après.

4. La page d'accueil marche, mais rafraîchir n'importe quelle autre page donne un 404

Votre app utilise du routage côté client (React Router ou un outil similaire). La première visite marche parce que le site charge index.html ; quand vous rafraîchissez /about, l'hébergeur cherche un vrai fichier à /about, n'en trouve pas, et renvoie un 404.

Solution : configurez l'hébergeur pour renvoyer index.html sur les chemins inconnus.

Netlify — ajoutez un fichier _redirects au dossier déployé :

/*    /index.html   200

Cloudflare Pages — sert généralement index.html par défaut pour les routes SPA inconnues ; si ce n'est pas le cas pour vous, ajoutez la même règle _redirects.

GitHub Pages — n'a pas ce fallback. Soit vous passez l'app en routage par hash, soit vous copiez index.html vers 404.html.

Astuce : certaines apps AI Studio embarquent déjà HashRouter (les URLs contiennent un #), ce qui évite complètement ce problème.

Le choix le plus sûr par défaut : exporter en fichiers statiques d'abord

Trois de ces quatre pièges partagent la même cause profonde : le code source a été déployé à la place d'un vrai build, ou le build a été envoyé avec une configuration qui ne correspond pas à l'hébergeur. Générez d'abord les fichiers statiques, puis déployez ces fichiers sur un hébergeur qui les sert depuis la racine — ça évite la plupart de ces problèmes avant même le déploiement. C'est le principe de Déployer une app Google AI Studio gratuitement (sans Cloud Run). Si c'est nouveau pour vous, faites d'abord tourner l'app en local pour être sûr que ça marche avant de la rendre publique.

FAQ

Pourquoi mon app Google AI Studio affiche-t-elle une page blanche après déploiement ?

Le plus souvent, parce que le dossier source a été envoyé à la place du dossier dist/ compilé, ou parce que le base path du build ne correspond pas à l'endroit où il est hébergé. Des variables d'environnement manquantes et le routage SPA sont les deux autres causes fréquentes.

Pourquoi j'ai des erreurs 404 sur mes fichiers JavaScript ?

Le base path ne correspond pas à l'endroit où l'app est hébergée. Réglez base dans vite.config.ts sur "/" pour un domaine racine ou "/your-repo/" pour un site de projet GitHub Pages, puis relancez le build.

Pourquoi un rafraîchissement de la page donne-t-il un 404 ?

Le routage côté client a besoin que l'hébergeur renvoie index.html pour les chemins inconnus. Ajoutez une règle _redirects sur Netlify ou Cloudflare Pages, ou utilisez le routage par hash sur GitHub Pages.

Est-ce sûr de mettre ma clé API Gemini dans l'app déployée ?

Non — une clé dans du code front-end est visible par quiconque ouvre le site. Pour tout ce qui est public, appelez Gemini via une fonction serverless pour que la clé reste côté serveur.