如何解决Bookdown与自定义LaTeX模板的hyperref包冲突问题？

问题根源 #

你碰到的LaTeX Error: Option clash for package hyperref，核心原因很明确：你的自定义模板sjtuthesis.cls已经在第83行通过\RequirePackage加载了带一系列参数的hyperref，但Bookdown在生成bookdown.tex时，又自动插入了\usepackage[unicode=true]{hyperref}，重复加载且参数不一致，直接触发了LaTeX的选项冲突错误。

实用解决方案 #

这里有几个经过验证的解决思路，按易用性排序：

1. 让Bookdown停止自动加载hyperref（推荐）

这是最直接的方案，既然你的模板已经处理好了hyperref的加载，就告诉Bookdown别多此一举。在你的RMD文件的YAML头部添加如下配置：

output:
  bookdown::pdf_book:
    latex_engine: xelatex  # 匹配你模板里的xetex选项
    keep_tex: true  # 可选，方便查看生成的tex文件调试
    extra_dependencies:
      hyperref: false  # 关键配置：禁用Bookdown自动加载hyperref

设置后，Bookdown生成的bookdown.tex里就不会再出现那行多余的\usepackage[unicode=true]{hyperref}了，完全复用你模板里的hyperref配置。

2. 给自定义模板加条件加载逻辑（如果允许修改模板）

如果你有权限修改sjtuthesis.cls，可以把hyperref的加载改成条件判断，避免重复加载：

\@ifpackageloaded{hyperref}{
  % 如果Bookdown已经加载了hyperref，就用hypersetup覆盖参数
  \hypersetup{
    xetex, bookmarksnumbered, colorlinks, 
    urlcolor=black, linkcolor=black, citecolor=black, 
    plainpages=false, pdfstartview=FitH
  }
}{
  % 没加载过的话，正常加载带参数的hyperref
  \RequirePackage[xetex, bookmarksnumbered, colorlinks, urlcolor=black, linkcolor=black, citecolor=black, plainpages=false, pdfstartview=FitH]{hyperref}
}

这种方法更灵活，不管Bookdown是否自动加载hyperref，都能保证最终的参数是你需要的，不会冲突。

3. 用preamble.tex统一hyperref参数

如果不想改模板也不想调整YAML的依赖配置，可以创建一个preamble.tex文件，提前指定hyperref的所有参数，让Bookdown加载时继承这些设置：

% preamble.tex
\PassOptionsToPackage{
  xetex, bookmarksnumbered, colorlinks, 
  urlcolor=black, linkcolor=black, citecolor=black, 
  plainpages=false, pdfstartview=FitH,
  unicode=true  # 兼容Bookdown默认的unicode参数
}{hyperref}

然后在RMD的YAML里引用这个文件：

output:
  bookdown::pdf_book:
    latex_engine: xelatex
    includes:
      in_header: preamble.tex

这样Bookdown加载hyperref时会优先读取你指定的选项，和模板里的参数保持一致，自然就不会冲突了。

验证步骤 #

设置完成后，记得开启keep_tex: true，然后重新编译，打开生成的bookdown.tex检查：确保只有一处hyperref的加载语句，且参数符合你的预期，之后再编译PDF就能正常生成了。

内容的提问来源于stack exchange，提问作者bubifengyun