PaperUI 的设计目标是开箱即用，但你总会有一些个性化的需求。这篇文章介绍如何在不直接修改主题源码的情况下，安全地自定义 PaperUI。 为什么不要直接修改主题源码 直接修改 themes/PaperUI/ 下的文件有几个问题： 主题更新困难：一旦修改了源码，git pull 更新主题时会产生冲突 可维护性差：其他人（包括未来的你）很难搞清楚哪些是改过的 升级风险：PaperUI 可能因 Hugo 版本更新而需要修改，你的改动会成为障碍 Hugo 的文件覆盖机制 Hugo 有一个重要的特性：项目根目录的同名文件会覆盖主题中的文件。 项目/ ├── themes/PaperUI/ │ └── layouts/ │ └── _partials/ │ └── footer.html ← 主题原始文件 └── layouts/ └── _partials/ └── footer.html ← 你的覆盖文件（优先使用） 这意味着你只需要在项目根目录创建相同路径的文件，Hugo 就会使用你的版本而不是主题的。 自定义主题颜色 PaperUI 使用 CSS 变量控制所有颜色。最简单的方式是在项目中创建覆盖样式文件。 创建 assets/css/extended/custom.css： /* 修改主题色 */ :root { --accent: #3b82f6; /* 蓝色系主题色 */ --accent-alpha: rgba(59, 130, 246, 0.1); --accent-secondary: #2563eb; /* 也可以修改其他变量 */ --content: #1a1a2e; --content-secondary: #4a4a6a; --border: #e5e7eb; } /* 深色模式 */ .dark { --accent: #60a5fa; --accent-alpha: rgba(96, 165, 250, 0.15); --content: #e5e7eb; --content-secondary: #9ca3af; --border: #374151; } PaperUI 默认的 accent 色是 #f87c45（暖橙色），你可以改成任何颜色。 ...

这是 PaperUI 系列文章的最后一篇。我们汇总了使用过程中的常见问题，并分享一些搭建 Hugo 博客的最佳实践。 常见问题 Q: 文章不显示？ 最常见的原因：日期设为未来日期。 Hugo 默认不渲染未来日期的文章。 解决方法：确保文章 Front Matter 中的 date 是今天或过去的日期。开发时可以用 hugo server -F 预览未来日期的文章。 Q: 首页轮播不显示？ 检查以下几点： hugo.toml 中是否配置了 [params.homeCarousel] 轮播图片路径是否正确（相对于 static/ 目录） 图片文件是否真实存在 Q: 侧边栏没有内容？ 侧边栏的"随机文章"和"近期文章"需要有足够数量的文章才会显示。建议至少有 3 篇以上的文章。 “分类"和"标签"小部件需要文章配置了对应的 categories 和 tags 才会出现。 Q: 搜索功能不工作？ PaperUI 的搜索依赖 fuse.js，需要确保： [outputs] 中包含 JSON（生成搜索索引） 文章没有被标记为 searchHidden: true 浏览器控制台没有 JS 错误 Q: 修改配置后不生效？ Hugo 开发服务器会自动检测配置变更并重载。但如果修改了主题文件或 CSS，建议重启 hugo server。 如果是修改了 baseURL 或 env 等影响输出的配置，需要重新构建。 Q: 如何添加评论系统？ PaperUI 没有内置评论系统（与 PaperMod 一致），但可以通过扩展模板添加。 ...