案例与资源 常见问题

在管理后台的案例库与资源模块中，最常遇到的三个问题是：案例和资源到底怎么关联、保存后关联为什么消失、以及上传附件为何不显示。这篇文章直接给你可复现的检查步骤与真实排查方法——看完你就能自己解决 90% 的操作故障。

案例与资源模块的核心机制

案例库本质是一个内容容器，每条案例可以绑定多个不同类型的资源文件。资源包括文档、图片、压缩包等，两者之间是多对多的关联关系。理解这个关系比记住菜单路径更重要：案例和资源各自独立存储，仅在关联表中建立映射。 所以，如果你只保存了案例正文但没保存关联关系，资源信息就相当于不存在。

延伸阅读：claude 搭建企业知识库、linux do claude.md怎么写

从架构上看，案例库通常位于“高级内容管理”模块下，资源管理则是一个平级的独立功能。两者通过一个中间表维护关系，使用资源 ID 而非名称作为外键。这就是为什么直接粘贴资源链接会失效——资源 ID 在系统迁移或重命名后可能变掉，而基于 ID 的关联会自动更新。

操作前必须检查的 4 个前置条件

跳过任何一项，后续步骤都可能失败。按顺序逐一确认：

1. 模块是否已启用
   在系统设置中搜索“内容管理”或“高级内容”，确认对应开关已打开。不同版本的开关名称可能不同：v2.3 叫“启用内容管理模块”，v3.0 改名为“高级内容管理”。该开关默认关闭。

2. 你的权限级别
   至少需要“编辑”权限。检查路径：系统设置 → 角色与权限 → 找到你的角色 → 查看“案例与资源”下的操作权限。只读权限只能查看，无法创建或关联。

3. 浏览器兼容性
   使用 Chrome 116+、Edge 116+ 或 Firefox 118+。操作系统不限。Safari 15 以下版本的富文本编辑器可能出现字段错位——双击编辑器后光标定位异常，这是已知兼容问题。

4. 准备测试数据
   新建一条测试案例（名称随意）和一个测试资源（比如一个 100KB 的示例 PDF）。所有首次操作都应使用测试数据，避免在生产数据上试错。

分步操作：添加案例并绑定资源

以下步骤按实际操作顺序排列。调换顺序会导致关联建立失败或数据丢失。

步骤 1：进入案例管理页面

在左侧导航树中找到“案例与资源”节点，展开后点击“案例列表”。如果导航树中没有这个节点，回到前置检查第 1 项。

步骤 2：创建新案例

点击“新建案例”按钮，填写以下必填字段：

• 案例名称：不超过 20 个汉字。避免包含 /、\、#、@ 等特殊符号，这些字符在部分后端系统中会被转义或截断。
• 案例标识符（slug）：系统自动生成一串随机字符，但建议手动改成简短易懂的英文或拼音，例如 case-upload-log-fail。标识符用于 URL 和系统内部引用，一旦发布就不能修改（除非有额外权限）。
• 所属分类：从下拉列表中选择一个已有分类。分类列表为空时，先去“资源分类管理”创建至少一个分类。分类名称最好用名词，避免用“综合”“其他”这种无区分度的词。
• 状态：保持“草稿”直到内容编辑完成。发布前随时可以更改。

步骤 3：编写案例正文

在富文本编辑器中编写案例描述。粘贴来自 Word 或网页的文本时，编辑器可能卡顿或布局错乱——因为粘贴的内容带入了大量无用样式标签。标准做法：使用编辑器工具栏的“粘贴纯文本”按钮，或者先把内容粘贴到记事本再复制过来。

需要引用已有资源时，使用编辑器内的 @资源名称 自动提示功能。这个功能基于系统资源的索引，输入 @ 后 1-2 秒会出现下拉列表，选择对应资源即可。不要手动粘贴资源链接——硬编码的链接在资源 ID 变更或系统迁移后会变成死链。

步骤 4：关联资源

在案例编辑页底部找到“关联资源”区域，点击“添加资源”。搜索或从列表中选择属于同一分组的资源。一个案例最多可关联 10 个资源，一个资源可以被多个案例关联。

关键操作：关联后必须点击“保存关联”按钮。这个按钮位于关联资源区域底部，不是页面顶部的“保存”按钮。只点击页面顶部的“保存”只会保存案例正文和字段，关联表不会被写入。这是最常见的遗漏点，几乎每个新手都会遇到一次。

步骤 5：上传附件（可选）

支持的格式：PDF、PNG、JPG、ZIP。单个文件不超过 20MB。拖拽文件到上传区域，等待进度条走完后再执行下一步。注意：上传过程中切换到其他页面会导致上传中断且无任何提示——进度条消失后你并不知道上传失败。

上传后检查文件名：如果文件名包含中文或空格，某些 Linux 服务器的文件系统可能不兼容，表现为上传成功但文件无法预览或下载。建议将文件名改为纯英文字母加数字。

步骤 6：预览并发布

点击“预览”查看最终效果。重点检查三项：

• 资源引用是否显示（在正文中出现资源名称，可点击跳转）
• 附件列表是否正确呈现
• 移动端布局是否正常（单列、文字不溢出）

确认无误后，点击“发布”。发布后案例立即可供其他用户查看，但关联资源的变更需要等待缓存刷新——通常 1-2 分钟内更新。如果在发布后立即访问案例页看不到关联资源，不要慌张，等 2 分钟再刷新。

发布后的 4 项检查清单

检查项	预期结果	如结果不符
案例页面是否显示关联的资源列表	在案例正文下方或侧边栏展示资源名称和简短描述	回到步骤 4，检查是否点击了“保存关联”
点击资源名称是否跳转到资源详情	新页面打开对应资源的完整信息	资源可能被删除或权限变更；检查资源管理页的状态
附件是否可预览或下载	图片直接嵌入页面，PDF/ZIP 显示下载按钮	文件上传失败；删除附件后检查文件名是否含中文/空格，重新上传
移动端视图下布局是否正常	文字不溢出、按钮可点击、资源列表单列显示	富文本中是否有过宽表格或未缩放的图片；使用编辑器“清除格式”后重试

故障排除：6 个高频问题与解决方法

案例保存后资源关联丢失

原因：只点击了页面顶部的“保存”按钮，没有点击底部的“保存关联”按钮。
解决方法：再次编辑案例，进入关联资源区域，查看已有条目是否还在。如果条目为空，需要重新添加。添加后务必点击“保存关联”。这条路径的机制是：案例正文和关联关系由两个不同的接口处理，顶部按钮只触发第一个接口。

富文本编辑器中的 @ 引用不生效

原因：@ 引用功能依赖系统预加载的资源索引。如果当前系统中没有任何已发布的资源，@ 后不会有任何提示。
解决方法：先去资源管理页创建并发布至少一个资源，再回到案例编辑器使用 @。如果资源已创建但仍不生效，刷新页面并清除浏览器缓存。有时候编辑器组件缓存了旧的索引列表。

附件上传成功后页面不显示

原因：文件格式或大小被服务端拒绝，但前端未给出明确错误提示。常见场景：

• 文件名包含中文或空格（某些服务器配置不允许）
• 文件超过 20MB
• 文件格式为 .exe、.bat、.sh 等被系统安全策略拦截的可执行格式
  解决方法：将文件重命名为纯英文名（例如 report-2024.pdf），确认文件小于 20MB，并检查格式是否在白名单内。如果仍然失败，尝试换一个浏览器上传。

发布按钮灰色不可点击

原因：必填字段未完成。最常遗漏的两个：

• 案例标识符（slug）未填写
• 所属分类未选择
  解决方法：检查表单顶部是否有红色提示信息。标识符可以手动填入，分类必须从下拉列表选择，不能自己输入。

移动端布局错乱

原因：正文中使用了表格、多列布局或高亮代码块——这些元素在移动端窄屏下会变形。
解决方法：最佳做法是在正文中尽量使用段落和列表，复杂表格以附件形式上传。如果必须嵌入表格，限制列数不超过 3 列，且每列文字长度不超过 15 个汉字。代码块建议使用编辑器支持的代码语法高亮，而非直接粘贴格式化文本。

关联资源的变更未在案例页面实时更新

原因：缓存机制导致的延迟。关联关系的变更需要 1-2 分钟才能刷新到前端页面。
解决方法：等待 2 分钟后刷新页面。如果超过 5 分钟仍不更新，检查资源是否已发布（草稿状态的资源不会在前端显示），以及资源本身是否被删除或权限