Skip to content

Home

Jump to bottom
天然純真 edited this page Jan 4, 2026 · 21 revisions

欢迎来到 Tufted-Blog-Template Wiki 页！

本页面可能遇到的一些困难和问题提供了帮助参考，如果阅读后仍然不能解决，你可以：

  • 向 AI 详细描述你遇到的问题，包括你正在干什么、你在哪一步遇到困难等等
  • 如果是和模板本身有关的问题，欢迎在 Issue 中查找或提问
  • 如果是和模板本身无关的问题，欢迎在 Discussions 中发言、提问、讨论

帮助文档

常见问题

  • Q: 提示 uv 或 python 或 typst 不是内部或外部命令/命令未找到？
    • 说明安装工具时，它们的路径没有成功添加到 PATH 环境变量中。请参考 Wiki 文档。
  • Q: 如何设置网站的浏览器标签图标？
    • 准备好你的图标，修剪好尺寸，命名为 favicon.ico，放入 assets/ 路径中，然后使用 --force 命令运行一次强制全新编译。
  • Q: 为什么我修改后网站没有更新？
    • 需要将修改后的文本重新 git push 到 GitHub，才会触发自动构建和部署。
  • Q: 为什么我推送后网站没有更新？
    • 虽然 Typst 编译很快，但整个工作流仍然需要大约半分钟的时间。如果等待后仍没有更新，尝试 Ctrl + F5 强制刷新页面，或检查 GitHub Actions 是否出错。
  • Q: 为什么我的网站首页显示的是 README.md 的内容？
    • 按照 Wiki 页 的说明，将 GitHub Pages 的源指定为 GitHub Actions，然后重新部署。
  • Q: GitHub Actions 构建失败怎么办？
    • 通常意味着你的 .typ 文件中存在错误，导致编译器在云端运行失败。点击失败任务查看详细日志（Log），通常会指出是哪个文件的哪一行出错了。请务必先在本地运行 uv run build.py build 或 make build 确保无误后再推送到远程。
  • Q: 我想提供 PDF 或 xx 文件供读者下载，应该放在哪里？
    • 你可以将这些文件放入当前链接页面的同级路径下，也可以在 assets/ 下新建一个 files 文件夹，然后把文件随 .typ 文档一起提交到 GitHub，构建网页时会自动复制你的文件。你只需要确保 .typ 文档中的相对路径链接能够正确链接到你的文件即可。
  • Q: 某个样式我不喜欢，我能不能自己修改？
    • 当然可以，你可以通过修改 assets/ 中的 custom.css 样式文件和 JS 脚本来配置任何你想配置的效果。但请不要根据自己审美偏好提交关于样式的 Issue，除非这是一个样式 BUG。
  • Q: 为什么某个功能/样式/包在 PDF 中可以正常使用，在网页却中没有效果？
    • Typst 的 HTML 导出功能仍处于实验性质，有些功能还不受支持，但未来可期。
  • Q: 为什么某个功能在网页上的显示异常？
    • 如果你认为该异常是模板本身的原因，请提交 Issue 反馈。
  • Q: Typst 中如何添加图片/表格/引用/.../实现某个功能/设置某个样式？
    • 关于 Typst 的使用问题，请查阅 Typst 文档、Wiki 文档、项目自带的“Typst 功能速览与样例”文档以及列出的其他资料，或询问 AI (Gemini 3 和 Claude 4.5 对 Typst 相对友好)。如果无法解决，可以在 Discussions 中提问讨论。
  • Q: 如何删除示例内容？
    • 删除 content/ 下不需要的路径和 .typ 文件。
  • Q: 为什么图片显示不出来？
    • 尝试使用 --force 命令运行全新编译，检查代码中引用的文件名大小写是否与实际文件完全一致，必须始终使用相对路径引用图片或内部链接。
  • Q: 为什么图片在本地能显示，部署到 GitHub 上就挂了？
    • 检查你的图片是否被正确提交到 GitHub，检查代码中引用的文件名大小写是否与实际文件完全一致，必须始终使用相对路径引用图片或内部链接。
  • Q: 为什么内容更新不及时？
    • 使用 --force 命令运行全新编译，编译完成后使用 Ctrl + F5 强制刷新浏览器页面。
  • Q: 为什么我设置的字体无效/我该如何自定义字体？
    • 网页会自动加载部分固定字体（如英文衬线字体），剩余的字体会使用浏览器的默认字体。如果你想为你的网站添加自定义字体，你需要将字体文件放入 assets/ 中，并修改样式文件。
  • Q: 我可以使用我自己的自定义域名吗？
  • 未完待续...

Clone this wiki locally