| 问题 | 处理 |
|---|
| 打开 /calcel/ 显示 JSON「用户未登录」 | 多为静态页被鉴权拦截；请使用已修复拦截器（仅拦截 *.do）的 WAR 版本 |
| 登录后仍跳回登录页 | 检查 API 路径是否为 /calcel/；反向代理是否转发 Authorization 头；清除浏览器 localStorage 后重试 |
| 发布到云端菜单不显示 | 检查 calcel.yml 中 cloudTemplateUrl 是否已配置且地址有效 |
| 发布到云端失败「用户未登录」 | 云端 JWT 与本地不一致，或云端未部署登录功能；确认两端为同版本 |
| 预览到的不是最新云端模板 | 本地 modfiles 存在同名文件时会优先使用本地版本；删除或重命名本地文件后再预览 |
| 版本列表为空 | 该模板尚未有过覆盖保存，首次保存不产生版本记录 |
| 拖放字段没反应 | 先通过「插入 → 插入数据集」打开面板并确认字段已加载；只能拖到画布单元格区域 |
| 扩展不出多行 | 检查主格是否纵向扩展 + 主单元格，且含有 ${ds.col} 或返回数组的公式；数据集预览是否有数据 |
| 参数在 SQL 里不生效 | 参数名与 #{名称} 一致；保存参数后重新预览 |
| 水印不显示 | 模板水印未启用时使用全局水印；两者都需启用并保存 |
| 填报提交找不到单元格 | 扩展区字段映射用设计时坐标（如 C5），勿填扩展后的运行时行号 |
| 富文本整格同色 | 用 <font color='...'> 标签或从 XLSX 导入 |
| 自定义函数保存失败 | 检查 function 名与声明一致；被调用的其他自定义函数须已保存 |
| 设计器浮动图不显示 | 表达式来源在设计器仅为占位，请改用 URL 或 本地图片；或预览报表查看解析结果 |
| 预览 / PDF 图片空白 | 检查表达式是否解析出 URL；URL 是否可访问（跨域）；数据集是否有对应行数据 |
| 浮动图预览上传无法保存 | 「预览可编辑」仅临时显示，写库请用图片单元格 + 填报属性 |
| 帮助章节加载失败 | 确认 public/help/chapters/ 下对应 html 文件存在；清除浏览器缓存后重试 |