常见问题
访问问题
应用更新服务后，访问页面还停留在原有页面？
原因
静态资源（HTML、CSS、JS、图片等）被 CDN 节点或浏览器缓存了， 导致访问的仍是旧版本内容。
解决方案
方案一：URL 追加路由参数强制刷新（推荐用于快速验证）
在访问链接后追加一个随机查询参数，绕过 CDN 和浏览器缓存，立即拉取最新内容：
# 原访问链接
https://my-env-123.xxx.tcloudbaseapp.com/
# 追加时间戳参数强制刷新（参数名可自定义，值唯一即可）
https://my-env-123.xxx.tcloudbaseapp.com/?v=20260422
https://my-env-123.xxx.tcloudbaseapp.com/?t=1745304000
https://my-env-123.xxx.tcloudbaseapp.com/index.html?_=random123
原理
CDN 会将带不同查询参数的 URL 视为不同资源，触发回源拉取最新内容。此方法适合快速验证部署结果，无需等待 CDN 缓存过期或手动刷新。
方案二：手动刷新 CDN 缓存（推荐用于生产环境）
前往 CDN 控制台 - 刷新预热，提交 URL 或目录刷新任务。刷新完成后所有用户即可访问到最新版本。
方案三：浏览器强制刷新（本地调试用）
- Windows / Linux：
Ctrl + F5或Ctrl + Shift + R - macOS：
Cmd + Shift + R - 或打开浏览器开发者工具（F12）→ Network 面板勾选 Disable cache
长期优化建议
对于构建产物，建议在构建阶段为静态资源文件名添加 内容哈希（如 app.a1b2c3.js），每次内容变更时文件名自动变化，从根本上避免缓存问题。主流构建工具（Vite、Webpack、Next.js 等）默认已开启该能力。
静态资源访问时出现 514 错误是什么原因？
原因
触发了 IP 访问限频配置。IP 访问限频是针对静态托管资源请求的总次数限制，而不是单个文件的请求次数限制。当用户访问一个网页时，浏览器会同时请求页面中的所有静态资源（HTML、CSS、JS、图片等），每个资源都会计入该 IP 的访问频率统计。
例如，假设您的网页包含：
- 1 个 HTML 文件
- 3 个 CSS 文件
- 5 个 JS 文件
- 10 个图片文件
用户访问时会产生 19 个并发请求。如果 IP 访问限频设置为 2 QPS，那么会有 17 个请求被拒绝，返回 514 错误。
解决方案
-
检查页面资源数量
- 使用浏览器开发者工具查看网络请求数量
- 统计页面加载时的总资源数
-
调整 QPS 设置
- 进入云开发控制台 → 环境配置 → 安全管控 → 静态托管安全配置
- 将 QPS 阈值设置为页面资源数的 1.5-2 倍
- 例如：页面有 20 个资源，建议设置 QPS 为 30-40
-
分页面类型设置
- 简单页面（5-10 个资源）：建议 QPS 20-30
- 普通网站（15-30 个资源）：建议 QPS 50-80
- 富媒体页面（50+ 个资源）：建议 QPS 100-200
注意
设置过低的 QPS 限制会影响正常用户的页面加载体验，建议根据实际业务需求合理配置。
构建问题
构建失败，提示 "command not found"
原因
缺少必要的构建工具或命令拼写错误。
解决方案
- 检查
package.json中是否定义了对应的 script - 确认构建命令拼写正确
- 检查是否安装了所需的依赖
构建超时
原因
项目依赖过多或构建过程复杂。
解决方案
- 开启构建缓存
- 优化依赖，移除不必要的包
- 使用更快的包管理器（如 pnpm）
部署路径问题
部署后页面空白或 404
原因
路径配置不正确或路由模式问题。
解决方案
- 检查
base/publicPath配置是否正确 - 单页应用（SPA）需要配置路由重定向
- 确认输出目录配置正确
静态资源 404
原因
资源路径引用错误。参考子路径部署配置
解决方案
- 使用相对路径引用资源
- 检查
base配置是否与实际部署路径一致 - 确认资源文件已正确构建到输出目录