前端构建、部署与浏览器调试

学习目标：理解开发服务器与生产构建的区别，能定位静态资源、路由、缓存和网络配置导致的上线问题。

1. 开发、构建与运行是三件事

开发服务器提供热更新和便利代理；生产构建把模块转换、分包、压缩并生成静态资源；部署平台负责把资源送到浏览器并把 API 请求转发到后端。开发环境 npm run dev 成功，不证明构建产物在生产路径下能访问。

常见工具如 Vite 会将客户端可访问的环境变量嵌入构建结果。客户端环境变量是公开数据。API 基础地址可以放进去，数据库密码和服务端密钥不能。部署前用生产构建预览，并在浏览器 Network 面板确认请求真正打向预期服务。

2. SPA 路由与静态资源路径

单页应用在客户端处理 /notes/42，但浏览器刷新时会直接向服务器请求这个路径。服务器需把应用路由回退到 index.html，同时保留真实 404、API 路径与静态资源路径。若应用部署在 /app/ 子路径下，构建工具的 base path、路由 basename 和资源 URL 必须一致。

症状	常见原因	核查位置
首页可用，详情刷新 404	缺少 SPA 路由回退	Web 服务器/平台路由规则
JS/CSS 404	base path 错误或旧缓存	HTML 中资源 URL、Network 面板
页面显示空列表	API 请求失败被吞掉	Network 响应、错误状态 UI
本地跨域正常，线上失败	代理/CORS/Cookie 配置不同	请求来源、响应头与凭证模式

3. 缓存与发布一致性

带内容哈希的 JS/CSS 可长时间缓存；index.html 通常需要更短缓存或再验证，因为它引用最新资源。发布时先确保新静态资源可用，再切换 HTML；过早删除旧资源会让仍持有旧 HTML 的用户加载失败。CDN 缓存、服务工作线程和浏览器缓存可能各有一层，排查时要区分来源。

Sourcemap 能帮助定位线上错误，但可能暴露源码细节；决定是否公开、上传到受控监控服务以及保留期限。日志与监控中不能包含令牌和敏感笔记正文。

4. 浏览器调试顺序

Console：看语法异常和资源加载错误，但不要只看最后一行。
Network：核对 URL、方法、状态码、响应体、缓存来源、Cookie 与 CORS 响应头。
Elements/Accessibility：检查实际 DOM、标签、焦点与计算样式。
Performance：记录加载和交互，找长任务、布局跳动和不必要的渲染。
复现条件：记录浏览器版本、窗口宽度、网络、登录状态和发布版本。

5. 实践任务

把同一笔记前端分别部署在根路径 / 与子路径 /app/；验证直接访问详情、刷新、退出登录、API 失败和静态资源缓存。故意配置错误 base path 与错误 API 地址，练习用 Network 面板定位差异，再写下修复与回滚步骤。