Quartz 项目部署常见问题及子模块管理规范

本文系统总结在 Quartz 框架中配置自定义组件（如 Profile）时遇到的远程部署异常及其技术方案，旨在规范带子模块（Submodule）项目的同步与维护流程。

1. 部署异常现象描述

1. 构建过程异常终止：报错提示 Import "Profile" will always be undefined。通常由于远程构建环境缺失对应的组件源文件。
2. 静态资源或布局渲染失效：远程页面未按预期加载自定义布局（Layout），或头像等图片资源请求返回 404 状态码。

2. 核心技术原因分析

1. 子模块内容未同步：新增组件存储于 quartz/ 子模块目录。在主项目目录执行常规的提交操作无法追踪子模块内部的未提交变更。
2. 远程仓库映射偏移：.gitmodules 中的 URL 记录仍指向原始仓库而非个人派生分支。GitHub Actions 在初始化子模块时将无法检索到个人版本库中的专用提交记录。
3. 配置文件层级读取差异：Quartz 的有效布局文件位于项目根目录 quartz.layout.ts。修改子模块内部的同名副本不会影响主项目的渲染效果。
4. 子路径部署下的路径解析冲突：站点部署于 GitHub Pages 子路径（如 /chico-quartz/）时，绝对路径引用（如 /static/avatar.png）由于指向域名根目录而导致资源定位失败。

3. 标准化同步方案

针对涉及子模块的更新，应执行以下标准化流程：

1. 同步子模块变更：
   • 切换至子模块目录：cd quartz
   • 执行推送：git add . → git commit → git push origin HEAD:refs/heads/v4
2. 同步根目录配置与资源：
   • 更新根项目 quartz.layout.ts 以确保布局逻辑一致。
   • 确保根项目 static/ 目录中包含所需的静态资源，以供构建插件正确引用。
3. 集成相对路径解析机制：
   • 在组件开发中使用 Quartz 内置的 resolveRelative 方法处理路径，确保在子域及子路径环境下能正确通过相对关系定位资源。
4. 更新主项目引用状态：
   • 返回根项目目录：cd ..
   • 同步指针与相关配置：git add quartz quartz.layout.ts static/
   • 执行版本提交并推送：git push

4. 维护与排障指南

• fatal: not our ref：验证子模块是否已上行推送至与其关联的远端个人仓库。
• 头像资源加载失败：确认资源物理存储于根目录 static/，并检查相关组件代码是否符合路径动态解析规范。
• 布局配置未更新：检查根目录环境下的 quartz.layout.ts 是否已同步本地变更。

---

Created: 2026-02-27