Oh My CV专业指南：从核心原理到高级应用

一、核心概念解析

1.1 本地化渲染引擎架构

Oh My CV采用本地优先（Local-First）架构设计，所有简历数据均存储在浏览器IndexedDB中，通过Nuxt.js的服务端渲染能力实现初始页面加载，后续编辑操作完全在客户端完成。这种架构确保了数据隐私性和离线可用性，核心实现逻辑位于site/src/utils/database.ts中，通过封装IndexedDB API提供数据持久化能力。

1.2 Markdown简历结构规范

简历文档采用YAML Front Matter+Markdown的复合结构：

---
name: 张三
contact:
  email: [e-mail]
  phone: [phone]
---
# 教育经历
- 2018-2022 某大学 计算机科学与技术 本科

元数据区域（Metadata）使用---分隔，支持任意键值对定义；内容区块通过Markdown标题（#）划分，每个标题对应简历的一个模块。这种结构设计既保持了纯文本的可移植性，又提供了结构化数据支持。

1.3 字体渲染系统原理

应用内置三级字体加载机制：

1. 系统字体回退：通过CSS font-family声明优先使用系统预装字体
2. 本地字体嵌入：将字体文件放置于site/src/assets/fonts目录，通过@font-face规则加载
3. 网络字体加载：通过gfonts-loader模块（packages/gfonts-loader/src/index.ts）实现Google Fonts的按需加载

字体渲染流程由dynamic-css模块（packages/dynamic-css/src/index.ts）动态生成内联样式，确保在不同设备上的一致性展示。

二、场景化解决方案

2.1 学术简历排版方案

适用场景：包含大量技术公式和学术成果的简历

1. 数学公式排版

   • 使用$...$包裹行内公式：$E=mc^2$
   • 使用$$...$$创建块级公式：

   $$
   \sum_{i=1}^{n} x_i = \int_{a}^{b} f(x) dx
   $$
   

   • 公式渲染由markdown-it-katex插件（packages/markdown-it-katex/src/index.ts）处理，基于KaTeX实现高效渲染

2. 文献引用格式

   • 使用交叉引用语法[[文献列表#引用1]]创建内部链接
   • 在"文献列表"章节使用特殊标记{#引用1}定义引用锚点
   • 实现逻辑位于packages/markdown-it-cross-ref/src/index.ts

注意事项：复杂公式可能导致PDF导出时排版异常，建议公式块前后保留空行

2.2 多版本简历管理策略

适用场景：针对不同职位定制差异化简历内容

1. 版本创建流程

   • 基础版本保存：点击工具栏"文件"→"保存"（触发database.ts中的saveResume方法）
   • 衍生版本创建：使用"另存为"功能生成新副本（实现于site/src/components/edit/toolbar/File.vue）
   • 版本命名规范：建议采用[职位名称]-[公司名称].md格式命名

2. 差异化内容管理

   • 使用条件渲染语法<!-- IF:dev -->开发经验<!-- ENDIF:dev -->控制内容显示
   • 通过主题切换功能（site/src/composables/stores/style.ts）保存不同排版方案
   • 利用导出选项指定不同内容过滤规则

注意事项：版本数量建议控制在5个以内，过多版本会增加维护成本

三、问题诊断框架

3.1 PDF导出异常排查流程

开始排查 → 检查字体设置 → 使用系统字体? → 是 → 检查页边距设置
                                       ↓ 否
                                  替换为系统字体
                                            ↓
                              检查内容溢出 → 有溢出 → 调整字体大小/段落间距
                                            ↓ 否
                                      检查图片格式 → 包含WebP? → 转换为PNG/JPG
                                                              ↓ 否
                                                         导出成功

关键排查点：

• 字体嵌入问题：非系统字体可能无法正确嵌入PDF，对应源码site/src/utils/css.ts中的embedFonts函数
• 内容溢出检测：通过site/src/utils/css.ts的checkContentOverflow方法可提前发现潜在问题
• 图片处理逻辑：位于site/src/components/ResumeRender.vue的图片预处理流程

3.2 数据迁移与恢复方案

当遇到浏览器数据丢失时，可按以下步骤恢复：

1. 数据恢复路径

   • 自动备份：系统每30分钟自动创建备份（database.ts中的autoBackup函数）
   • 手动恢复：通过"文件"→"导入"选择本地备份文件
   • 版本回溯：在"文件历史"中选择恢复点（实现于site/src/components/resumes/ResumeOptions.vue）

2. 预防措施

   • 启用云同步：定期导出.md文件至云存储
   • 备份策略：建议每周至少创建1次手动备份
   • 数据验证：通过"文件"→"验证"检查文档完整性

四、专业优化清单

优化类别	检查项	优化建议	实现路径
内容质量	技能描述具体化	使用"动词+量化结果"格式描述	N/A
排版规范	字体一致性	标题与正文字体区分，不超过2种字体	site/src/assets/css/index.css
性能优化	资源加载	移除未使用字体，减少自定义CSS	site/src/utils/font.ts
兼容性	跨设备预览	在移动设备和打印预览中检查布局	site/src/components/Preview.vue
数据安全	备份频率	重要更新后立即备份	site/src/components/edit/toolbar/File.vue

五、高级功能解析

5.1 自定义主题开发

Oh My CV支持创建自定义主题，通过修改CSS变量实现个性化样式：

1. 主题开发步骤

   • 创建主题文件：在site/src/assets/css/themes/目录下新建.css文件
   • 定义CSS变量：

     :root {
       --primary-color: #2c3e50;
       --text-color: #333333;
       --section-spacing: 1.5rem;
     }
     

   • 注册主题：在site/src/utils/constants/data.ts中添加主题定义

2. 主题应用逻辑 主题切换通过style.ts中的setTheme方法实现，动态替换:root选择器的CSS变量值，无需页面刷新即可生效。

5.2 自动化内容生成

通过内置的模板系统快速生成标准内容模块：

1. 模板使用方法

   • 打开"插入"菜单，选择所需模块模板（如"工作经验"、"项目经历"）
   • 填写模板表单，系统自动生成Markdown内容
   • 模板定义文件位于site/src/utils/constants/default.ts

2. 自定义模板创建

   • 复制现有模板格式，添加自定义字段
   • 通过site/src/components/edit/toolbar/ToolItem.vue添加模板入口
   • 实现动态表单生成逻辑

六、校验模块

核心概念校验

常见误区：将Markdown元数据区域误认为普通内容 解决方案：确保元数据区域以---开始和结束，且位于文档最顶部 验证方法：通过"工具"→"文档结构检查"验证格式正确性

场景应用校验

常见误区：过度使用自定义字体导致跨设备兼容性问题 解决方案：优先使用系统安全字体，如Arial、Georgia等 验证方法：在"预览"模式下切换"模拟不同设备"检查显示效果

高级功能校验

常见误区：自定义主题未定义完整的CSS变量集 解决方案：使用site/src/utils/css.ts中的validateTheme函数检查完整性 验证方法：切换主题后检查控制台是否有CSS变量警告