症状 (Symptoms)

本地打开 /navi/index.html 后，百度地图提示“未授权使用地图 API”，看起来像浏览器端百度地图密钥失效或被删除。

根因 (Root Cause)

frontend/public/navi/ 是独立的 vanilla JavaScript 静态页面，不经过 Vite 的模块编译。其 app.js 中的 FALLBACK_BROWSER_AK 按设计是 __BAIDU_BROWSER_AK__ 占位符。

真实浏览器端 AK 来自根目录 .env 的 VITE_BAIDU_BROWSER_AK，来源分两条：

  • 从 SPA 首页进入导航页时，src/shared/navi.js 通过 import.meta.env.VITE_BAIDU_BROWSER_AK 将 AK 追加为 ?ak=。
  • 生产构建后，scripts/inject-browser-ak.cjs 将 AK 注入 frontend/dist/navi/app.js。

因此直接使用 Vite 访问裸路径 /navi/index.html，或直接启动未注入的 public 目录，会把占位符传给百度地图，产生未授权提示。这不等同于 .env 中的 key 被删除。

正确操作 (Correct Operation)

开发调试优先从 http://127.0.0.1:8300/ 首页进入导航页。若必须直接打开导航页，URL 需显式携带 ?ak=<VITE_BAIDU_BROWSER_AK>。

生产/静态构建必须按顺序执行：

node node_modules/vite/bin/vite.js build
node scripts/inline-module.cjs
node scripts/inject-browser-ak.cjs

Windows 仓库路径包含 & 时，npm 的 .bin shim 可能解析错误；用 Node 直接入口是项目既有约定，不是绕过构建流程。inject-browser-ak.cjs 只改 dist，不要把真实 AK 写回 public/navi/app.js，也不要把 dist 当源码编辑。

验证 (Validation)

  1. 检查根 .env 是否存在 VITE_BAIDU_BROWSER_AK。
  2. 检查 src/shared/navi.js 生成的导航 URL 是否包含 ak=。
  3. 检查 dist/navi/app.js 的 FALLBACK_BROWSER_AK 不再等于 __BAIDU_BROWSER_AK__。
  4. 浏览器强制刷新，确认百度地图脚本请求中的 ak 与 .env 的 AK 一致。

关联项目

  • campus-navi-rs/frontend/README.md
  • campus-navi-rs/README.md
  • campus-navi-rs/frontend/scripts/inject-browser-ak.cjs

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/Frontend