Quartz项目中如何正确引入外部JavaScript资源

2025-05-26 01:59:26作者：钟日瑜

在Quartz项目开发过程中，开发者经常需要引入第三方JavaScript资源来增强网站功能。本文将详细介绍在Quartz框架中正确引入外部脚本的方法。

问题背景

许多开发者尝试直接在共享组件中通过head属性引入外部JavaScript资源，例如：

export const sharedPageComponents: SharedLayout = {
  head: Component.Head(
    {externalResources: {js: [{src: "https://example.com/script.js", crossorigin: "anonymous", loadTime: "beforeDOMReady"}]}},
  ),

然而这种方法在Quartz v4版本中并不能正常工作，脚本不会如预期那样出现在<head>标签中。

正确解决方案

Quartz框架的设计要求外部资源必须在transformer层进行配置。具体操作步骤如下：

定位到项目中的quartz/plugins/transformers/ofm.ts文件（或其他您正在使用的transformer文件）
在transformer配置中添加外部资源：

export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>> = {
  // ...其他配置
  externalResources() {
    const js: ExternalResource[] = [
      {
        src: "https://example.com/script.js",
        loadTime: "beforeDOMReady",
        contentType: "external",
      },
    ]
    
    const css: ExternalResource[] = [
      {
        content: "https://example.com/style.css",
        inline: false,
      },
    ]
    
    return { js, css }
  },
}

实现原理

Quartz框架采用模块化设计，所有外部资源的加载都集中在transformer层处理。这种设计有以下几个优点：

统一管理：所有外部资源集中配置，便于维护和更新
加载控制：可以精确控制资源加载时机（DOM加载前或后）
性能优化：框架可以统一处理资源预加载、缓存等优化策略

扩展应用

除了JavaScript文件，同样的方法也适用于引入CSS样式表：

css.push({
  content: "https://cdn.example.com/library/version/style.min.css",
  inline: false,
})

注意事项

确保使用HTTPS协议的CDN资源以保证安全性
考虑添加crossorigin属性处理跨域请求
对于关键资源，建议指定loadTime: "beforeDOMReady"以确保及时加载
保持资源URL的版本控制，避免缓存问题

通过遵循Quartz框架的资源加载规范，开发者可以安全高效地集成各种第三方资源，同时保持项目的可维护性和性能优化。

quartz

🌱 a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites

项目地址：https://gitcode.com/GitHub_Trending/qua/quartz

登录后查看全文

项目优选

收起

kernel

deepin linux kernel

docs

OpenHarmony documentation | OpenHarmony开发者文档

Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用

本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。

C++

535

pytorch

Ascend Extension for PyTorch

Python

RuoYi-Vue3

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统

旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件，通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求，让密码技术应用更简单，同时探索后量子等先进算法创新实践，构建密码前沿技术底座！

1 K

397

community

本项目是CANN开源社区的核心管理仓库，包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息

385

openGauss-server

openGauss kernel ~ openGauss is an open source relational database management system

C++

146

191