用Typst高效制作专业简历：从排版原理到工程化实践

1. 项目概述：用Typst高效制作专业简历

最近在帮朋友整理求职材料，也顺带回顾了一下自己的简历。我发现一个挺有意思的现象：很多技术背景的朋友，简历内容本身很扎实，但最终的排版和呈现效果却总差那么点意思。要么是Word调格式调到崩溃，要么是LaTeX写起来太“重”，要么就是用在线工具导出的PDF格式不统一。我自己也经历过这个阶段，直到我开始用Typst来写简历，整个体验才变得顺畅起来。

Typst是一个新兴的、专门为科技文档设计的排版系统。它有点像LaTeX的现代化、轻量化版本，语法更简洁，编译速度飞快，而且对中文等非拉丁语系文字的支持也相当不错。这个项目kiwamizamurai/resume-typst就是一个基于Typst的简历模板，它提供了日式风格的履历书和职历书（也就是我们常说的简历和详细的工作经历描述）的生成方案。对于正在求职，尤其是关注细节、希望简历在格式上也能体现专业性的开发者或工程师来说，这是一个非常值得研究的工具。

简单来说，这个项目能帮你用代码（Typst脚本）来定义简历的样式和内容，然后一键生成格式精美、排版一致的PDF文件。你不再需要手动拖动文本框、调整行距，所有样式都通过代码控制，修改起来既快又准，还能用Git进行版本管理，非常适合需要频繁更新简历的求职者。接下来，我会详细拆解这个项目的使用、定制方法，并分享一些在制作技术简历时的实操心得。

2. 核心思路与工具选型解析

2.1 为什么选择Typst而不是Word或LaTeX？

在决定使用任何工具前，搞清楚“为什么”是关键。对于简历制作，我们通常有几个选择：Microsoft Word/Google Docs、LaTeX、HTML/CSS，以及像Typst这样的新兴工具。

Word/Google Docs的痛点在于可控性差。看似“所见即所得”，但一旦内容稍多，格式就容易“跑飞”。调整一个段落的间距，可能引发连锁反应；跨设备编辑时，字体缺失、版式错乱更是家常便饭。最重要的是，它无法进行版本控制，你很难清晰地回溯“上个月投A公司时我改了什么描述”。

LaTeX是学术界的标准，排版能力强大，生成的PDF极其专业。但它的学习曲线陡峭，环境配置复杂，编译速度慢（尤其是涉及中文时），而且语法对于只想写份简历的人来说过于冗长和底层。你常常需要引入一大堆宏包，只为调整一个列表的样式。

Typst的定位就很巧妙。它吸收了LaTeX在排版和内容分离上的精髓（你用纯文本写内容，用样式规则控制格式），但语法设计得非常现代和友好。它内置了现代化的功能，比如更智能的数学排版、对SVG和Emoji的原生支持，以及毫秒级的编译速度。对于简历这种结构相对固定、但样式要求精致的文档，Typst的优势非常明显：你用简单的几行代码就能定义出漂亮的样式，然后专注于内容本身。所有文件都是纯文本，完美契合Git，你可以为不同公司定制不同版本的简历，轻松管理和对比。

2.2 项目结构浅析：简历（Resume）与职历书（CV）的区别

这个模板项目提供了两个输出：resume.pdf和cv.pdf。这对应了日式求职文档体系中常见的两种文件，理解它们的区别对用好模板很重要。

简历（Resume / 履歴書）通常是一到两页的摘要，高度浓缩。它包含你的基本信息、联系方式、教育背景、工作经历（只列公司、职位、时间）、核心技能和关键成就。目的是让招聘者在10-30秒内对你有一个快速、清晰的印象。因此，简历的排版需要极度清晰、易读，重点突出，留白合理。

职历书（CV / 職務経歴書）则更为详细，可能有多页。它会展开描述每一段工作经历中的具体职责、参与的项目细节、使用的技术栈、取得的量化成果以及个人贡献。它更像一份个人工作报告，用于通过简历初筛后，在面试环节供面试官深入参考。

这个Typst模板分别提供了针对这两种文档的优化样式。resume模板偏向紧凑和高效的信息展示，而cv模板则提供了更多的空间来描述细节和项目经历。在实际求职中，通常需要同时准备这两种文档，这个项目一次性解决了两个需求。

2.3 核心依赖：Typst与HackGen字体

项目的依赖非常简单，核心就两个：Typst引擎和HackGen字体。

Typst的安装与管理：作者推荐通过mise来管理Typst。mise是一个跨平台的多版本运行时管理工具（类似于asdf或nvm），可以让你轻松安装和切换不同版本的Typst。这对于确保编译环境的一致性非常有用。当然，你也可以直接从Typst官网下载安装包或使用包管理器（如brew install typst）安装全局版本。使用mise的好处是，项目目录下会有一个.tool-versions文件，锁定特定的Typst版本，任何克隆你项目的人都能获得完全一致的编译环境，避免了“在我机器上好好的”这类问题。

字体的选择——HackGen：这是一个非常明智的选择。HackGen是日本开发者将等宽字体“Hack”与日文字体“源柔ゴシック”（GenRyu Gothic）合并而成的字体家族。它的特点是：

1. 等宽与比例字体的和谐：英文部分基于Hack，是优秀的编程等宽字体，清晰易读；中文部分基于源柔ゴシック，是一款现代、优雅的黑体。
2. 中西文混排效果出色：由于是专门合并设计的，中英文之间的字重、基线对齐都非常协调，避免了混合使用不同字体时常见的“高低不齐”、“粗细不一”的问题。
3. 包含Nerd Font符号：项目也安装了font-hackgen-nerd，这意味着你可以在简历中直接使用那些漂亮的开发图标（比如Git、Docker、Kubernetes、各种编程语言的Logo），让你的技能列表更加直观和专业。对于技术简历来说，这是一个巨大的加分项。

注意：如果你主要面向国内企业求职，需要确认HackGen字体中文字符集的完整性。对于绝大多数常用汉字，它没有问题。但如果涉及非常生僻的字，或者你希望使用其他中文字体（如思源黑体、霞鹜文楷），在Typst中更换字体也是非常容易的，后续在定制章节会讲到。

3. 环境配置与初体验

3.1 一步步搭建你的Typst简历环境

让我们从零开始，把这个项目跑起来。假设你使用的是macOS系统，Linux和WSL2下的操作也基本类似。

第一步：安装mise（可选但推荐）如果你还没有安装mise，可以通过以下命令安装：

curl https://mise.jdx.dev/install.sh | sh

安装完成后，重启你的终端，或者运行source ~/.bashrc(或~/.zshrc) 来加载mise。

第二步：克隆项目模板找一个你存放代码的目录，执行：

git clone https://github.com/kiwamizamurai/resume-typst.git cd resume-typst

这样你就得到了项目的所有源文件。

第三步：安装项目指定的Typst版本进入项目目录后，mise会自动读取.tool-versions文件。你可以直接运行以下命令来安装文件中指定的Typst版本：

mise install

或者，你也可以手动安装Typst。如果不想用mise，可以去Typst官网下载对应系统的二进制文件，或者用Homebrew安装：brew install typst。确保typst --version命令可以执行。

第四步：安装HackGen字体根据项目说明，使用Homebrew安装：

brew install --cask font-hackgen font-hackgen-nerd

对于Windows用户，可以去HackGen的GitHub Release页面下载.ttf文件，然后直接安装。Linux用户同样可以下载字体文件，复制到~/.local/share/fonts/目录下，然后运行fc-cache -fv刷新字体缓存。

第五步：首次编译生成PDF环境就绪后，编译就非常简单了。项目在package.toml中定义了几个脚本：

• mise run cv: 生成详细的职历书（CV）
• mise run resume: 生成简洁的简历（Resume）
• mise run build: 同时生成两者

直接在项目根目录下运行：

mise run build

如果一切顺利，你会在resume和cv两个子目录下看到新生成的resume.pdf和cv.pdf。用你的PDF阅读器打开它们，就能看到模板的默认效果了。

3.2 理解项目目录结构与核心文件

成功编译后，我们来看看项目的骨架，这是后续进行自定义的基础。

resume-typst/ ├── cv/ │ ├── cv.pdf # 编译生成的职历书PDF │ └── main.typ # 职历书的主Typst文件 ├── resume/ │ ├── resume.pdf # 编译生成的简历PDF │ └── main.typ # 简历的主Typst文件 ├── assets/ # 可能存放图片、图标等资源 ├── components/ # 可复用的Typst组件（如联系方式块、技能条） ├── lib.typ # 全局的样式、函数、颜色定义库 ├── package.toml # 项目元数据和脚本定义 ├── README.md └── .tool-versions # mise使用的版本锁定文件

核心文件解读：

1. lib.typ：这是整个项目的“样式大脑”。它定义了文档的全局样式，比如页面大小、页边距、字体、颜色主题、标题样式、列表样式等。所有自定义的样式调整，大部分都会在这里进行。
2. components/目录：这里存放着模块化的代码片段。例如，可能有一个contact.typ文件，里面定义了如何渲染姓名、电话、邮箱、GitHub链接的组件。这种设计极大地提高了代码的复用性和可维护性。你想修改联系方式在所有文档中的呈现方式，只需要改这一个文件。
3. resume/main.typ和cv/main.typ：这是两个入口文件。它们通过#import语句引入lib.typ中的样式和components/中的组件，然后组织具体的内容（你的个人信息、经历等）。你编辑简历内容，主要就是修改这两个文件。
4. package.toml：Typst的项目清单文件。它定义了项目名称、版本、入口文件，以及最重要的——脚本。我们看到[script]部分定义了cv、resume、build这几个命令，它们本质上是在调用typst compile命令并指定对应的入口文件。

理解这个结构后，你就会明白，定制简历分为两个层面：样式定制（修改lib.typ和components/）和内容填充（修改resume/main.typ和cv/main.typ）。

4. 深度定制：打造属于你的个人品牌简历

直接使用模板生成的PDF只是开始。一份出色的简历必须打上你个人的烙印。下面我们从内容到样式，一步步进行深度定制。

4.1 内容填充：用数据驱动你的简历

首先打开resume/main.typ。你会看到文件内容是由Typst代码和你的信息混合组成的。Typst使用#符号来标识函数和指令。你需要找到类似下面的内容块进行修改：

// 示例结构，非原文件精确内容 #let name = "你的名字" #let title = "求职意向，例如：高级后端工程师" #let contact = components.contact( phone: "+86 138-xxxx-xxxx", email: "your.email@example.com", github: "your-github-id", location: "城市，国家" ) #show: resume.with( name: name, title: title, contact: contact, education: [ // 教育经历数组 components.education( institution: "你的大学", degree: "学士/硕士", major: "专业", period: "2015.09 - 2019.06", details: "相关课程或荣誉（GPA，奖学金等）" ), // ...可以添加多个教育经历 ], experience: [ // 工作经历数组 components.experience( company: "上一家公司", role: "职位", period: "2020.03 - 至今", location: "工作地点", details: [ // 工作职责和成就，使用Markdown式的列表 [- 负责XX系统的架构设计与核心开发，日处理请求量从10万提升至500万。] [- 引入Kafka消息队列，解耦了A、B服务，使系统延迟降低了40%。] [- 主导了团队代码规范的制定，并通过CI/CD流水线进行自动化检查，代码评审效率提升30%。] ] ), ], skills: components.skills( languages: ["Go", "Python", "JavaScript"], frameworks: ["Gin", "React", "Kubernetes"], tools: ["Docker", "Git", "AWS EC2/S3", "Prometheus"] ) )

内容填充的核心原则：

• 使用强动词和量化结果：避免“负责”、“参与”这类模糊词汇。多用“设计”、“实现”、“优化”、“主导”、“将...提升了X%”、“减少了Y成本”。量化结果最具说服力。
• 针对职位定制：不要用一份简历海投。仔细阅读职位描述（JD），提取关键词，并将你经历中与之匹配的部分调整顺序、强化描述。你可以利用Git分支功能，为不同类型的职位（如“后端开发”、“DevOps”、“技术负责人”）创建不同版本的内容分支。
• 技能列表要分层：像示例中那样，将技能分为“编程语言”、“框架/库”、“工具/平台”等类别，显得更有条理。对于你精通的和熟悉的，可以用不同方式标注（比如在components.skills函数中设计一个熟练度参数）。

4.2 样式定制：从颜色到布局的全面控制

样式定制主要在lib.typ文件中。Typst的样式系统非常强大且直观。

1. 修改颜色主题：在lib.typ中，通常会定义一些颜色变量，例如：

// 定义颜色变量 #let primary-color = rgb("#2e86ab") // 主色调，可用于标题、分隔线 #let secondary-color = rgb("#a23b72") // 辅助色，可用于链接、高亮 #let text-color = rgb("#333333") // 正文颜色 #let muted-color = rgb("#666666") // 次要信息颜色

你可以将这些十六进制颜色代码替换成任何你喜欢的颜色。推荐使用低调、专业的颜色，如深蓝、深灰、墨绿等，避免使用过于鲜艳刺眼的颜色。一个主色调贯穿始终，能让简历看起来更统一、专业。

2. 调整字体：虽然HackGen很棒，但你也可以更换。首先确保你的系统安装了目标字体，然后在lib.typ中修改字体定义：

// 设置中英文分别使用的字体 #set text( font: ("LXGW WenKai Screen", "SimSun", serif), // 中文优先使用霞鹜文楷屏幕版，回退到宋体 fallback: ("HackGen", "Microsoft YaHei", sans-serif) // 回退字体 )

Typst的font参数可以接受一个数组，它会按顺序尝试加载字体。这对于中英文混合排版非常有用，可以为不同语言指定最合适的字体。

3. 调整页面与段落样式：

// 设置页面，例如A4纸，页边距 #set page( paper: "a4", margin: (top: 2.5cm, bottom: 2cm, left: 2.5cm, right: 2.5cm) ) // 设置标题样式 #show heading: set text(weight: "bold", size: 1.3em) #show heading.where(level: 1): set block(above: 1.2em, below: 0.8em) // 一级标题的上下间距 // 设置列表样式 #show list: set list(marker: [—]) // 将默认的圆点改为破折号 #show list.item: set par(first-line-indent: 0pt) // 列表项首行不缩进

通过这些设置，你可以精细控制简历的每一处细节，包括行距、段前段后间距、项目符号样式等。

4. 创建或修改组件：组件的魔力在于复用。假设你想在联系方式里增加一个个人博客的链接，并且用一个特定的图标表示。 首先，在components/目录下找到或创建contact.typ，修改其函数定义，增加blog参数：

// components/contact.typ #let contact(phone, email, github, location, blog) = { // 使用Nerd Font图标 #set text(font: "HackGen Nerd Font") #grid( columns: (1fr, 1fr, 1fr, 1fr, 1fr), // 调整为5列 gutter: 1em, [#icon("phone") #phone], [#icon("mail") #link(email)], [#icon("brand-github") #link("https://github.com/" + github)], [#icon("map-pin") #location], [#icon("world") #link(blog)] // 新增博客项 ) }

然后，在resume/main.typ中调用这个组件时，传入你的博客地址即可。这种方式使得添加、删除或重新排列联系信息变得非常简单。

实操心得：样式调整时，建议一次只修改一个变量，然后编译查看效果。Typst的编译速度极快（通常不到1秒），这让你可以像前端开发一样获得即时反馈，极大地提升了定制效率。另外，将你的自定义颜色、字体等也定义为变量，并集中放在lib.typ文件的开头，这样未来想要换一套主题色会非常方便。

5. 高级技巧与自动化工作流

5.1 利用Git进行简历版本管理

这是使用代码编写简历的最大优势之一。你可以为简历创建一个Git仓库（这个模板项目本身就是一个仓库）。

• 主分支（main）：存放你最新、最通用的简历版本。
• 功能分支：当你想尝试一个全新的版式设计时，可以创建一个feat/redesign分支，大胆修改lib.typ，而不用担心破坏主分支的稳定性。
• 公司定制分支：针对你心仪的公司A，创建分支company-a，根据其JD微调经历描述和技能关键词。针对公司B，再创建分支company-b。
• 提交信息：使用有意义的提交信息，如“feat: 添加AWS认证技能”、“fix: 修正项目时间描述”、“style: 调整主色调为深蓝色”。这样你的简历进化史一目了然。

当你需要投递时，切换到对应的分支，编译生成PDF即可。这种管理方式，是任何图形化工具都无法比拟的。

5.2 集成CI/CD：自动生成与部署

你可以更进一步，利用GitHub Actions或GitLab CI等持续集成服务，实现“提交即发布”。每次你向GitHub推送修改，CI会自动运行typst compile，将生成的PDF作为构建产物（Artifact）提供下载，甚至可以直接发布到你的个人网站。

一个简单的GitHub Actions工作流示例（.github/workflows/build.yml）：

name: Build Resume PDF on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Typst uses: typst-community/setup-typst@v2 with: version: 'latest' - name: Install HackGen Font run: | wget -O hackgen.zip https://github.com/yuru7/HackGen/releases/download/v2.9.0/HackGen_v2.9.0.zip unzip -j hackgen.zip "*.ttf" -d ~/.local/share/fonts/ fc-cache -fv - name: Compile PDFs run: | typst compile resume/main.typ resume/resume.pdf typst compile cv/main.typ cv/cv.pdf - name: Upload PDFs as Artifact uses: actions/upload-artifact@v4 with: name: generated-pdfs path: | resume/resume.pdf cv/cv.pdf

这样，你可以在任何地方通过浏览器访问GitHub仓库的Actions页面，下载最新生成的简历，无需本地环境。

5.3 处理多语言简历

如果你需要中英文双语简历，有几种策略：

1. 并行文件：创建resume-zh.main.typ和resume-en.main.typ，分别存放中英文内容，但共享同一套lib.typ样式。这是最清晰的方式。
2. 条件编译：在同一个文件中，通过定义变量来控制显示哪种语言。

   #let lang = "en" // 或 "zh" #let name = if lang == "en" { "Your Name" } else { "你的名字" } #let title = if lang == "en" { "Software Engineer" } else { "软件工程师" } // ... 其他所有文本都这样处理

   然后通过命令行参数或环境变量传递lang值给Typst脚本（Typst支持从JSON文件读取数据，这为实现该功能提供了可能）。这种方式更高级，但初始设置复杂一些。

对于大多数情况，我推荐第一种“并行文件”方案，简单直接，不易出错。

6. 常见问题与排查技巧实录

在实际使用中，你可能会遇到一些问题。这里记录了一些常见的情况和解决方法。

6.1 编译错误与排查

问题1：mise命令未找到或typst命令未找到。

• 原因：环境变量未正确配置。
• 解决：确保已按照安装步骤操作，并重启了终端。对于mise，可以运行mise activate或查看其安装后的提示。对于直接安装的Typst，确认其安装路径已加入系统的PATH环境变量。

问题2：编译时报字体错误，如Font ... not found。

• 原因：Typst在系统中找不到lib.typ中指定的字体。
• 解决：
  1. 确认字体已正确安装。在macOS的“字体册”、Windows的“字体设置”中查看。
  2. 对于Linux，确保字体文件在~/.local/share/fonts/或/usr/share/fonts/目录下，并运行了fc-cache -fv。
  3. 在Typst文件中使用更通用的字体族名称（如sans-serif,serif）作为回退（fallback）。
  4. 可以使用命令typst fonts来列出Typst可识别的所有系统字体，确认你的字体在其中。

问题3：生成的PDF中文显示为方框或乱码。

• 原因：使用的字体不包含所需的中文字形。
• 解决：确保你指定的中文字体确实支持中文。将中文字体放在font数组的首位，并提供一个可靠的回退字体列表。例如：#set text(font: ("Source Han Sans SC", "Microsoft YaHei", sans-serif))。

6.2 内容与样式优化中的“坑”

问题4：内容溢出页面，或者最后一页只有一点点内容。

• 原因：内容长度控制不当。
• 解决：
  • 精简内容：简历贵在精炼。反复审视每句话，删除冗余词汇，合并同类项。
  • 调整样式：微调lib.typ中的page(margin: ...)，适当减小页边距可以增加可用空间。或者调整#set par(line-spacing: ...)行距，以及各级标题的above/below间距。
  • 使用分页控制：Typst提供了#pagebreak()等指令，但简历中应谨慎使用，尽量通过内容裁剪来保持自然分页。

问题5：列表项描述过长，导致排版不美观。

• 解决：
  • 遵循“STAR”原则（情境、任务、行动、结果）来组织描述，使其简洁有力。
  • 在Typst中，可以对列表项使用悬挂缩进，让多行文本对齐。这通常在lib.typ的列表样式中定义。
  • 如果某一点成就特别突出，可以考虑将其单独列出，甚至加粗关键词。

问题6：如何插入公司Logo或个人头像？

• 解决：Typst支持直接嵌入图片。

  #image("path/to/your/logo.png", width: 1.5cm)

  将图片文件（建议使用PNG或SVG格式）放在项目目录下（如assets/），然后在.typ文件中使用相对路径引用。注意控制图片尺寸，避免喧宾夺主。

6.3 求职季的实用技巧

• 版本命名：生成PDF时，可以在文件名中加入版本信息或日期，例如张三_后端工程师_简历_202405.pdf，方便你和招聘方管理。
• ATS友好性：许多大公司使用申请人跟踪系统（ATS）来初筛简历。确保你的PDF是纯文本可选的（Typst生成的PDF默认就是），避免使用过多花哨的排版和图形，以免ATS解析失败。这个Typst模板生成的简历结构清晰，通常是ATS友好的。
• 打印测试：在发送前，务必用打印机打出一份纸质版看看效果。检查颜色在黑白打印下是否依然有足够的对比度，页边距是否合适。
• 文件大小：Typst生成的PDF通常很小。但如果插入了高分辨率图片，文件可能会变大。可以使用在线的PDF压缩工具进行优化，确保邮件附件不会过大。

从最初的克隆项目、安装环境，到深度定制样式、填充个性化内容，再到利用Git进行版本管理和CI自动化，用Typst制作简历不仅仅是一个“生成PDF”的动作，它更是一种将工程化思维应用于个人品牌塑造的实践。它迫使你更结构化地思考自己的经历和技能，同时也给了你无限的自由度去呈现最好的自己。当你把简历的源文件也放进GitHub仓库，它本身就成了你“注重工具链”、“追求自动化”、“拥有代码审美”这些软技能的一个小小证明。