为什么指定参考文献 CSL 后，报错“failed to load CSL style”？

Typst 已经内置了中文常用的 GB/T 7714—2015 格式；如果你使用了其它中文 CSL 样式，可能会遇到这种报错。

概论

在读取 CSL 样式方面，Typst 目前^[1]已基本完全支持 CSL 标准。这些样式之所以无法加载，通常是因为用了非标准特性，例如 CSL-M 扩展和 citeproc-js 内部特性。

对此有两种解决思路：

其实大部分非标准特性只影响特殊情况。可以先删除非标准特性，让 Typst 能读取样式生成参考文献；等真的遇到特殊情况了，再专门解决或手动编辑。
使用 Citext 替代 Typst 原生的参考文献引擎，支持非标准特性。
这种方法可以根除问题，但会拖慢编译，而且有时需要调用特殊函数而不能单纯@key。详见另一页面的专门小节。

下面具体介绍第一种方法。

如何删除非标准特性

TIP

对于 Zotero 中文社区的 CSL 样式，不必阅读后文，可直接前往可用于 Hayagriva 的 CSL 样式下载批量修改好的版本。

首先需定位问题。请将文件上传到 CSL Validator，选择 CSL 1.0.2 (current)，正常应出现下面这种结果。

Oops, I found 8 errors.
Errors
Line 42: Bad value citation-range-delimiter for attribute name on element term from namespace http://purl.org/net/xbiblio/csl.
xml
ms>
  <term name="citation-range-delimiter">-</ter
…

CSL Validator 提示 No errors found，但 Typst 仍然无法加载 CSL？

CSL Validator: Good job! No errors found.

CSL Validator 与 Typst/Hayagriva 毕竟原理不同，“CSL Validator 认为合法”与“Typst 认为合法”其实并无严格蕴含关系。

遇到这种情况，可尝试用 Typst 持续编译文档，然后二分法依次删除各个<macro>来定位问题。

接着结合 Typst 的报错，逐一修改各项错误。

例如上例可能伴随 Typst 报错 data did not match any variant of untagged enum Term，与 CSL Validator 第一个错误写的 term 相关，那就找到 CSL 文件的第 42 行，删除或注释citation-range-delimiter这行。修改后，如果 Typst 仍然无法加载 CSL，就继续处理下一个错误，直到解决。

以下列出了常见报错以及解决方法，大致按常见程度降序排列，可供参考。

duplicate field `layout`

Typst 暂不支持 CSL-M 标准，可以注释掉多余的 <layout> 临时解决。

在 CSL 文件里搜索 bibliography 和 citation，这里通常有多个 <layout> ，一般建议注释掉 <layout locale="en"> 这一段 <layout> 。例子如下

xml

<bibliography entry-spacing="0" et-al-min="4" et-al-use-first="3" second-field-align="flush">
  <!--
  <layout locale="en">
    <text variable="citation-number" prefix="[" suffix="]"/>
    <text macro="entry-layout"/>
  </layout>
  -->
  <layout>
    <text variable="citation-number" prefix="[" suffix="]"/>
    <text macro="entry-layout"/>
  </layout>
</bibliography>

（示例来自 Zotero 上的 China National Standard GB/T 7714-2015 (numeric, 中文)，原作者见此文件，依 CC-BY-SA 3.0 协议使用）

这样修改之后，CSL 根据文献语言自动使用“等”或“et al.”的功能会失效，请见如何修复英文参考文献中的“等”。

unknown variant `institution`, expected one of `name`, `et-al`, `label`, `substitute`

请在 CSL 文件里注释掉<institution/>。

xml

<macro name="secondary-contributors-en">
  <names variable="translator">
    <name/>
    <institution/>
    <!-- <institution/> -->
    <label form="short" prefix=" "/>
  </names>
</macro>

data did not match any variant of untagged enum Term

该错误有多种可能原因。

若 CSL 文件中包含citation-range-delimiter等非标准<term>，请删除它们，例如：

xml

<locale>
  <terms>
    <term name="citation-range-delimiter">-</term>
    <term name="page-range-delimiter">-</term>
  </terms>
</locale>

原因

按照 GB/T 7714—2015，同一处连续引用多篇文献时，起讫序号间用短横线连接，例如[255-256]。这个短横线默认是–（U+2013 EN DASH），以上citation-range-delimiter将它修改为-（U+002D HYPHEN-MINUS）。不过citation-range-delimiter超出了 CSL 规范和 CSL-M 扩展，是 citeproc-js 单独实现的，Typst 并不识别。

常见的非标准<term>如下。

citation-range-delimiter可删除
space-et-al可替换为et-al
en-et-al、zh-et-al、et-al-zh等也可替换为et-al
long-ordinal-11、long-ordinal-12（CSL 标准规定最大到 10）可删除

此外，个别 CSL 文件错误地把<term>当成<macro>用。这种情况需要理解文件原本意图才能改正，建议直接向 CSL 维护者提出。

data did not match any variant of untagged enum TextTarget/Variable

请替换非标准的变量（variable），例如：

xml

<if variable="original-container-title">
<if variable="container-title">
  <group delimiter=": ">
    <text variable="original-container-title"/>
    <text variable="container-title"/>
    <text macro="volume"/>
  </group>
</if>

常见的非标准变量及解决办法如下。

<text term="unpublished"/>是过时的 CSL-M 扩展，可替换为<text value="Unpublished"/>
标准之外的original-*变量可去除original-前缀，常见的有：
- original-container-title、original-container-title-short
- original-genre
- original-event-title、original-event-place
- original-editor
- original-status
- original-issue
- original-jurisdiction
<if variable="CSTR">涉及2025年新版国标引入的科技资源标识 (CSTR)，目前无法输入。可先在 CSL 删除整段<if>，然后在著录各篇文献时把CSTR: …作为文本夹带进相邻位置的字段。

此外，个别 CSL 文件错误地把变量当成<macro>用。这种情况需要理解文件原本意图才能改正，建议直接向 CSL 维护者提出。

missing field `$value`

CSL 标准规定<else>、<group>、<layout>等元素必须有内容。如果为空（或者只有注释），就会报告此错误。

对于<else>和<group>，通常是 CSL 维护者调试时忘记清理，直接把整段元素删掉即可。例如：

xml

<choose>
  <if variable="URL">
  <text variable="URL"/>
  </if>
  <else>
    <!-- <text variable="DOI" prefix="https://doi.org/"/> -->
  </else>
</choose>

对于<layout>，应该是工具性 CSL 刻意为之，可填充空字符串解决。

xml

<citation>
  <layout/>
  <layout>
    <text value=""/>
  </layout>
</citation>

unknown variant ``, expected one of `lowercase`, `uppercase`, `capitalize-first`, `capitalize-all`, `sentence`, `title`

请删掉空的text-case属性。

xml

<text variable="title" text-case=""/>
<text variable="title"/>

invalid locator

把locator属性改为标准规定的小写。

xml

<if locator="Chapter">
<if locator="chapter">

另请参见

贡献者

Y.D.X.

Copilot

Haoran SUN

QuadnucYard

页面历史

最后编辑于 5 个月前

查看完整历史

指 v0.14.0-rc.1 及之后的版本。 ↩︎

为什么指定参考文献 CSL 后，报错“failed to load CSL style”？

为什么指定参考文献 CSL 后，报错“failed to load CSL style”？ ​

概论 ​

如何删除非标准特性 ​

duplicate field layout ​

unknown variant institution, expected one of name, et-al, label, substitute ​

data did not match any variant of untagged enum Term ​

data did not match any variant of untagged enum TextTarget/Variable ​

missing field $value ​

unknown variant ``, expected one of lowercase, uppercase, capitalize-first, capitalize-all, sentence, title ​

invalid locator ​

另请参见

贡献者

页面历史

Preview:

为什么指定参考文献 CSL 后，报错“failed to load CSL style”？

概论

如何删除非标准特性

duplicate field `layout`

unknown variant `institution`, expected one of `name`, `et-al`, `label`, `substitute`

data did not match any variant of untagged enum Term

data did not match any variant of untagged enum TextTarget/Variable

missing field `$value`

unknown variant ``, expected one of `lowercase`, `uppercase`, `capitalize-first`, `capitalize-all`, `sentence`, `title`

invalid locator