GAS ウェブアプリが突然「開けない」— ブラウザ用ライブラリの混入と clasp push の盲点

症状

• Apps Script のウェブアプリが、直前のデプロイまで動いていたのに全画面で開けなくなる（Google のエラーページ、または真っ白）。
• doGet だけでなく、同じプロジェクトのトリガー関数や google.script.run もすべて失敗する。
• 直前のデプロイで「HTML 側の変更しかしていない」のに起きる。

原因

1. Node でのテスト用にプロジェクトのローカルフォルダへ置いたブラウザ用の minified ライブラリ（例: zxing.min.js、jspdf.min.js、chart.min.js など）が、clasp push でそのままサーバー側 .js として送られた。
2. Apps Script はプロジェクト内の全 .gs/.js を毎回の実行開始時にトップレベルから評価する。UMD 形式のライブラリは起動時に window / global / self を探し、Apps Script の V8 ランタイムにはどれも無い（globalThis はある）。多くのライブラリはそこで例外を投げる（例: Error: Can't search globals for BigInt!）。
3. トップレベルで例外が出るとすべてのエントリポイントが死ぬ。HTML が CDN から同じライブラリを読んでいるなら、サーバー側のコピーはそもそも不要。

診断手順（AI にそのまま実行させる）

1. 直前の版と現在の版の中身を Apps Script API で取り、ファイル一覧を比較する。
   • GET https://script.googleapis.com/v1/projects/<scriptId>/content?versionNumber=<N>
   • トークンは ~/.clasprc.json の tokens.default.access_token（clasp を1回動かすと更新される）。
   • 新しく増えたファイルがあれば最有力容疑。
2. 全サーバー .js を「Apps Script 相当のグローバル」で読み込む再現テストを回す（下記）。window/global/self/exports/module/define/require を存在しない名前として扱うのが肝。UMD の最初の分岐で exports や define がスタブに化けると、ライブラリ本体が実行されずに「読み込み OK」と誤判定する。

// gas-load.test.mjs — node gas-load.test.mjs --src <clasp pull したフォルダ>
import fs from 'node:fs'; import path from 'node:path'; import vm from 'node:vm';
const src = process.argv[process.argv.indexOf('--src') + 1];
const ABSENT = new Set(['window','document','navigator','self','global','exports','module','define','require']);
const base = {}; for (const k of Object.getOwnPropertyNames(globalThis)) { if (ABSENT.has(k) || k === 'globalThis' || k === 'process') continue; try { base[k] = globalThis[k]; } catch {} }
const stub = () => new Proxy(function(){}, { get: (t, p) => p === 'then' ? undefined : stub(), apply: () => stub(), construct: () => stub() });
let ok = true;
for (const f of fs.readdirSync(src).filter(n => n.endsWith('.js') || n.endsWith('.gs')).sort()) {
  const ctx = vm.createContext(new Proxy(base, { has: (t, p) => !ABSENT.has(p), get: (t, p) => ABSENT.has(p) ? undefined : (p in t) ? t[p] : (typeof p === 'symbol' ? undefined : stub()) }));
  try { vm.runInContext(fs.readFileSync(path.join(src, f), 'utf8'), ctx, { filename: f, timeout: 20000 }); console.log('✅', f); }
  catch (e) { ok = false; console.log('❌', f, '→', e.name + ': ' + e.message); }
}
console.log(ok ? 'ALL PASS' : 'FAIL'); process.exit(ok ? 0 : 1);

SpreadsheetApp 等の GAS 固有グローバルはスタブで握りつぶすので、通常の業務コードは「load OK」になり、混入ライブラリだけが落ちる。

修正手順

1. ローカルフォルダから混入ファイルを削除する。
2. clasp push -f は「ローカルに変更が無い」と Script is already up to date で何も送らず、リモートだけにあるファイルは消えない。この状態で clasp deploy すると、壊れたままの新バージョンができる。対処はどちらか:
   • Apps Script API で全ファイルを丸ごと送る: PUT /v1/projects/<scriptId>/content に { files: [{ name, type: 'SERVER_JS' | 'HTML' | 'JSON', source }] }（.clasp.json は含めない、appsscript は JSON）。
   • どれか 1 ファイルに実変更（コメント1行など）を入れてから push する。
3. clasp deploy --deploymentId <既存ID> で同じデプロイ ID に新バージョンを当てる（URL を変えない）。
4. read-back: GET /v1/projects/<scriptId>/deployments/<deploymentId> で versionNumber が新番号になっていること、GET .../content?versionNumber=<新番号> のファイル一覧に混入ファイルが無いこと、ローカルと byte 一致することを確認する。

再発防止

• テスト用ライブラリは clasp の rootDir の外（test/vendor/ 等、.clasp.json の rootDir 配下以外）に置く。または .claspignore に *.min.js を書く。
• push 前に上の gas-load.test.mjs を毎回通す。
• push 後に必ず HEAD の content をファイル名一覧で読み戻し、想定ファイル数と一致するか見る。
• デプロイ前の「本番との差分」は clasp pull の結果同士ではなく、版番号指定の API 取得で比較すると確実（clasp pull は HEAD しか取れない）。

落とし穴まとめ