企业官网建设流程全解析

我记得第一次看到Markvis，第一反应是：这不就是把Vega-Lite塞进Markdown里吗？但真正用了一阵子之后，我发现这个工具解决的其实是写文档最痛的那件事——图表和文档分离。

以前写技术博客或者数据周报，画一张图要经历：打开Excel或者Python调数据、设置颜色、导出PNG、找图床、上传、再回到Markdown里写图片链接。等数据更新了，整套流程再来一遍。如果图表里有六根柱子、两条折线，光传图和清缓存就能耗掉半天心情。Markvis把整个流程压缩成三步：在Markdown里写一个vis代码块，代码块里放JSON配置，生成静态页面时直接渲染成可交互的SVG图表。数据变了，回到代码块里改数字，刷新页面就是新图。文档里的图表不再是截图，而是图表本身，鼠标悬停还能看数值。

这篇文章我准备了三个可以直接照抄的案例——柱状图、折线图、饼图，从标记语法讲到编码原理，再往后是图层叠加、双Y轴组合、条件配色和transform数据预处理，最后梳理我实际使用中踩过的坑。想搞明白"在Markdown里优雅插图到底怎么落地"，照着这篇文章走一遍，基本就够了。

1. 先搞懂Markvis到底是怎么把代码变成图表的

1.1 一个vis代码块的完整生命周期

Markvis的核心思路其实很简单，它复用了Markdown代码块的语法，把vis当作一个特殊的语言标记来识别。整个过程可以拆成四步：

1. 在Markdown里写一个vis代码块，代码块里放的是JSON格式的图表配置
2. Hexo构建流程（或者其他Markdown渲染管线）扫描到vis标记时，不再按普通代码块处理
3. 插件取出代码块里的JSON文本，交给底层的Vega-Lite渲染引擎
4. Vega-Lite根据JSON里的数据源、标记类型、编码映射，在页面里生成SVG或Canvas图表

也就是说，当你写vis代码块的时候，本质上是在写Vega-Lite的spec（配置规范）。Markvis做的事是把"把spec嵌进Markdown并完成渲染"这层重复劳动包掉，让你专注于写数据和配置本身。

1.2 声明式图表语法到底是什么

很多教程上来就让读者堆JSON，但如果不理解底层的设计思想，遇到稍微复杂一点的需求就会卡壳。Vega-Lite是一套声明式可视化语法，用通俗的话讲就是：你只需要描述"我有什么数据、要把哪个字段映射到x轴、哪个字段映射成颜色、用什么几何形状来画"，剩下的比例尺计算、坐标轴刻度、图例生成、网格线排布统统由引擎自动完成。

这个和命令式画图的体验差异很大。传统方式画一条折线，你得写"从点(0, 0)画一条线到点(100, 50)"；声明式方式只需要写"横轴是月份，纵轴是销售额，用折线表示"。前者关心像素级操作，后者关心的是数据与视觉通道的映射关系。

给完全没接触过可视化配置的读者一个生活类比：声明式配置像你去饭馆点菜，你告诉服务员"来一份番茄炒蛋"，配菜、火候、装盘是后厨的事；命令式操作则是你自己冲进后厨拿起锅铲，每个步骤都要亲手控制。Markvis走的是彻底的点菜路线。

1.3 和Mermaid、截图方案的本质区别

说到Markdown里画图，很多人第一时间想到Mermaid，这里把主流方案放在一起对比一下，你就知道Markvis适合干什么了。

所以Markvis的定位非常清晰：它面向以Markdown为写作主线、需要在文档或博客里嵌入数据图表的人，让图表成为Markdown的一等公民，而不是挂在文中的一张外来图片。它不是一个比ECharts更强的图表库，而是把Vega-Lite这种成熟能力搬进Markdown生态的桥梁。

2. 环境准备：三种方式让Markdown能识别vis代码块

2.1 方式一：Hexo博客集成

Markvis最常见的宿主环境是Hexo博客，因为官方就提供了hexo-markvis插件。集成步骤不复杂，核心只有三步。

npm install --save hexo-markvis

如果你的Hexo版本没有自动加载插件，在站点配置文件_config.yml里加一条：

plugins: - hexo-markvis

然后重新生成并启动本地服务：

hexo clean hexo g hexo s

这里有一个很容易被忽视的细节：代码块的语言标记必须严格使用小写的vis。如果你写成了大写VIS，或者混进了空格，插件就认不出来，页面会原样显示JSON文本。我第一次用的时候就因为顺手写了大写，浪费了十几分钟查原因。

验证是否生效的方式也很简单：生成后打开页面，右键检查元素。如果能看到<svg>标签，说明解析成功；如果页面上还顶着一大段JSON，说明vis代码块没有被插件捕获，需要检查语言标记或者插件注册状态。

2.2 方式二：自己的前端项目里接入

除了Hexo，Markvis也能接入到其他Markdown渲染管线中，因为它的核心职责就是"扫描vis代码块，把JSON交给渲染引擎"。大致思路是：

1. 从npm安装markvis相关依赖
2. 在项目的构建脚本或者运行时入口引入它的渲染模块
3. 确保Markdown渲染流程会把vis代码块保留为可解析的元素，然后由Markvis执行渲染

这一步我没有贴死版本号和具体的API调用方式，原因很简单：这类早期开源项目API调整频率较高，不同版本的回调方式和导入路径可能不一样，直接看官方README是更稳妥的做法。我给你的排错思路是：装完先跑通一个最简单的图表，再往上叠加业务配置，不要一上来就追求复杂效果，否则出了问题你根本分不清是集成问题还是配置问题。

2.3 方式三：不想部署，先拿在线编辑器练手

如果你暂时不想折腾Hexo环境，只是想在本地文档里用Markvis写图表，可以先借助Vega-Lite官方在线编辑器来调试配置。打开Vega-Lite Editor的网页，把vis代码块里的JSON整个粘贴到左栏，右侧会实时渲染对应的图表。

这个办法我强烈推荐，尤其是教程里的配色、标签偏移、图例方向这些视觉细节，在线编辑器可以即时反馈，省掉反复构建部署的时间。等确认效果满意了，再把配置粘回Markdown里。养成"先在线验证配置，再进文档"的习惯之后，你遇到"部署后一片空白"的概率会直线下降。

2.4 版本和依赖关系

Markvis之所以能画出专业级的图表，底层靠的是Vega-Lite，所以它的配置规范就是Vega-Lite的spec。在Hexo集成场景下，安装hexo-markvis时npm会自动处理依赖关系。但如果你从网上抄了一段配置却渲染失败，有一个排查方向经常被忽略：Vega-Lite不同大版本之间，spec的写法存在差异，比如4.x和5.x对部分图层的写法就有微调。

我的建议是，在你的项目里确认一下实际安装的Vega-Lite版本，然后按对应版本文档去写配置。遇到"spec不合法"这类报错时，不要第一时间怀疑插件坏了，先想想版本对不对、JSON合不合法。

3. 案例一：柱状图——分类数据对比的入门首选

3.1 先写一个最基础的柱状图

假设你要在季度周报里展示全年四个季度的销售额。传统做法是Excel画图、截图、贴图，现在直接在Markdown里定义一个vis代码块：

{ "data": { "values": [ {"季度": "Q1", "销售额": 120}, {"季度": "Q2", "销售额": 180}, {"季度": "Q3", "销售额": 150}, {"季度": "Q4", "销售额": 210} ] }, "mark": { "type": "bar", "cornerRadius": 4 }, "encoding": { "x": {"field": "季度", "type": "nominal", "axis": {"title": "季度", "grid": false}}, "y": {"field": "销售额", "type": "quantitative", "axis": {"title": "销售额（万元）"}} } }

保存构建后，你会看到四根圆角柱子，y轴从0开始自动分段，季度名称沿x轴排开，柱子底色是Vega-Lite默认配色。鼠标悬停时通常也会弹出数值提示，不过如果想要完全控制tooltip内容，后面会讲到显式配置的方法。

这份配置值得逐段吃透：

• data.values：直接内联数据。后面改数据，只需要动这里
• mark：声明图表用柱子来画。cornerRadius给柱子加了圆角，视觉上比默认的直角样式柔和
• encoding.x：把"季度"字段映射到x轴。type设为nominal，意思是离散分类
• encoding.y：把"销售额"字段映射到y轴。type设为quantitative，引擎会按照数值特征自动计算坐标范围

3.2 增强：排序、自定义配色和数据标签

柱状图本身不难，真正的专业感来自细节。

第一，排序。默认情况下柱子的顺序按数据源顺序来，但人的视觉习惯对"由高到低"的排列更敏感。在x轴编码里加一个sort参数：

"x": { "field": "季度", "type": "nominal", "sort": "-y" }

sort设为"-y"表示按y轴字段降序排列。如果是做Top N排行榜，这个参数几乎是必写的。

第二，自定义配色。如果你希望每根柱子都有各自的颜色，在encoding里加color通道：

"color": { "field": "季度", "type": "nominal", "legend": null, "scale": { "range": ["#4C78A8", "#72B7B2", "#E45756", "#F58518"] } }

range里直接指定颜色的Hex值，用来覆盖默认配色。legend设为null是隐藏"季度"图例，因为x轴标签已经清楚标明了每根柱子代表什么，再放图例反而占版面。

第三，数据标签。柱子上方显示具体数字，需要叠加一个文本层。Markvis支持图层组合，一个vis块里可以定义多个layer依次叠加：

{ "layer": [ { "data": { "values": [ {"季度": "Q1", "销售额": 120}, {"季度": "Q2", "销售额": 180}, {"季度": "Q3", "销售额": 150}, {"季度": "Q4", "销售额": 210} ] }, "mark": {"type": "bar", "cornerRadius": 4}, "encoding": { "x": {"field": "季度", "type": "nominal"}, "y": {"field": "销售额", "type": "quantitative", "axis": {"title": "销售额（万元）"}}, "color": {"field": "季度", "type": "nominal", "legend": null} } }, { "data": { "values": [ {"季度": "Q1", "销售额": 120}, {"季度": "Q2", "销售额": 180}, {"季度": "Q3", "销售额": 150}, {"季度": "Q4", "销售额": 210} ] }, "mark": {"type": "text", "dy": -8, "fontSize": 12, "color": "#333"}, "encoding": { "x": {"field": "季度", "type": "nominal"}, "y": {"field": "销售额", "type": "quantitative"}, "text": {"field": "销售额", "type": "quantitative", "format": ".0f"} } } ] }

这段配置看着多，但逻辑很清楚：第一个layer画柱子，第二个layer在柱子上方写字。text字段会自动把"销售额"的值渲染成文本，format: ".0f"表示保留0位小数。dy: -8让文字比柱子顶端高8像素，避免紧紧贴在柱顶上。

这里补充一个经验：layer方式下，两个layer的数据源是独立的。如果你原本计划让柱子一组数据、标签另一组数据，很容易出现"柱子和标签对不上"的问题。最简单的做法是让两个layer使用相同的values内容，不要偷懒。

3.3 这个案例里隐藏的实用思路

柱状图写到这里，你可以对比一下传统方式：在Excel里画柱状图需要手动选数据区域、调坐标轴标题、去网格线、改颜色、导图片，还要保证图表风格统一。Markvis把所有这些都变成了可复用的JSON配置，数据变了，改一个数字，重新构建，图表和标签会自动同步更新。这也是它最被低估的价值——你的图表和文档不再依赖手动维护了。

4. 案例二：折线图——趋势分析的正确打开方式

4.1 多系列折线图的长表结构

柱状图适合分类对比，趋势变化就要用折线图。这里我直接用一个更贴近实战的场景：某产品12个月的新增用户和流失用户双线对比。

很多同学刚一接触Vega-Lite时，习惯用电子表格的思路整理数据，一行是一个月份，各列是各个指标。但Vega-Lite更偏爱"长表"结构：一行是一个取值，指标类型单独放在一列里。要看两条折线，数据通常是这样写的：

{ "data": { "values": [ {"月份": "1月", "指标": "新增用户", "人数": 320}, {"月份": "2月", "指标": "新增用户", "人数": 455}, {"月份": "3月", "指标": "新增用户", "人数": 398}, {"月份": "4月", "指标": "新增用户", "人数": 512}, {"月份": "5月", "指标": "新增用户", "人数": 604}, {"月份": "6月", "指标": "新增用户", "人数": 738}, {"月份": "1月", "指标": "流失用户", "人数": 120}, {"月份": "2月", "指标": "流失用户", "人数": 155}, {"月份": "3月", "指标": "流失用户", "人数": 132}, {"月份": "4月", "指标": "流失用户", "人数": 178}, {"月份": "5月", "指标": "流失用户", "人数": 190}, {"月份": "6月", "指标": "流失用户", "人数": 226} ] }, "mark": { "type": "line", "point": true, "strokeWidth": 2.5 }, "encoding": { "x": { "field": "月份", "type": "ordinal", "axis": {"title": "月份", "labelAngle": 0} }, "y": { "field": "人数", "type": "quantitative", "axis": {"title": "人数"} }, "color": { "field": "指标", "type": "nominal", "scale": {"range": ["#4C78A8", "#E45756"]}, "legend": {"title": "指标", "orient": "top"} } } }

这份配置的关键点：

• mark是line，point: true让每个数据点显示一个小圆点，采样位置一目了然
• color通道映射"指标"字段，两条折线自动分组，分别使用蓝和红
• 图例放在顶部（orient: "top"），因为有两个指标就有两个颜色，必须靠图例告知对应关系

4.2 为什么用ordinal而不是temporal

这是新手最容易困惑的地方。月份这种字段，既可以理解成有序分类，也可以理解成时间序列。我建议按数据格式来决定：

• 如果只有月份名或者"Q1"这种简写，用ordinal最稳。它不会试图解析成日期，也不会因为日期缺失导致断档
• 如果数据里是标准日期字符串，比如"2025-01-01"，用temporal才能享受时间轴的特殊能力，比如自动刻度、跨年断线、按季度聚合等

如果选错type会有什么现象？把月份错设成quantitative，字段里带有"月"字就会被当成非数字，整根线可能画不出来；设成nominal虽然能画，但顺序会按数据出现的顺序来，未必符合时间先后。所以看似是一个小的类型选择，实际决定了图表的可用性。

4.3 平滑曲线、虚线这些细节怎么调

想让折线更顺滑，在mark里加一行：

"mark": { "type": "line", "point": true, "strokeWidth": 2.5, "interpolation": "monotone" }

interpolation默认是linear，也就是直线段直接连接；改成monotone后曲线会平滑穿过数据点，又不会产生过度震荡，是报表里非常顺眼的一种形态。

如果想区分实际值和预测值，可以给预测那条线设置虚线。用strokeDash通道：

"encoding": { "strokeDash": { "field": "类型", "type": "nominal", "scale": {"domain": ["实际", "预测"], "range": [[], [6, 4]]} } }

range里第一个[]表示实线，第二个[6, 4]表示6像素实段加4像素空段。这样实际和预测一眼就能分开，颜色还可以自由指定。折线图这一节最后多说一句：如果只有一个序列，不需要写color通道，直接在mark里设置stroke颜色就够了。能用单色就别用多色，这是避免图表变花哨的基本原则。

5. 案例三：饼图——占比数据的环形与变形

5.1 基础饼图配置

饼图和柱状图、折线图最大的不同在于坐标系统。它不是简单地把字段映射到x/y轴，而是通过theta通道把数值映射为扇区弧度，再通过color通道按分类着色。如果你接触过D3的弧形生成器，理解起来会很快。

来看一个市场品牌份额的例子：

{ "data": { "values": [ {"品牌": "A品牌", "份额": 38}, {"品牌": "B品牌", "份额": 27}, {"品牌": "C品牌", "份额": 20}, {"品牌": "D品牌", "份额": 15} ] }, "mark": { "type": "arc", "innerRadius": 55, "outerRadius": 115 }, "encoding": { "theta": {"field": "份额", "type": "quantitative"}, "color": { "field": "品牌", "type": "nominal", "legend": {"title": "品牌", "orient": "right"}, "scale": {"range": ["#4C78A8", "#72B7B2", "#E45756", "#F58518"]} } } }

mark设为arc，这是饼图在Vega-Lite里的实现方式。theta通道负责角度，color通道负责分组配色。结构上它本质上是一个极坐标下的柱状图：分类字段走颜色通道，数值字段走角度通道。

我给innerRadius设了55，所以这里生成的是一个环形图。为什么会主动用环形？两个原因：一是实心饼图的扇区面积利用率低，如果直接在扇区里塞标签，文字重叠是家常便饭；二是环形图中间留出的空白区域，在排版上更透气，你甚至可以在中间放合计数值或者其他说明。对大多数数据报告来说，环形图通常比实心饼图更耐看。

5.2 排序和默认起始角度

饼图的扇区默认从12点方向开始顺时针排列，顺序按数据源里出现的先后。如果希望A品牌最大、排在最前面，并且扇区按数值降序排列，可以给theta通道加排序：

"theta": { "field": "份额", "type": "quantitative", "sort": {"field": "份额", "order": "descending"} }

这里的sort只影响扇区的排列顺序，不影响数值本身。如果数据是动态变化的，这个写法比手动调整values顺序高效得多。

5.3 让tooltip显示百分比

饼图的核心信息是占比。鼠标悬停时如果tooltip能直接显示百分比，看图的人就不用对着图例猜数字了。配置方式是在encoding里加一个tooltip数组：

"encoding": { "theta": {"field": "份额", "type": "quantitative"}, "color": {"field": "品牌", "type": "nominal", "legend": {"title": "品牌"}}, "tooltip": [ {"field": "品牌", "type": "nominal", "title": "品牌"}, {"field": "份额", "type": "quantitative", "title": "份额", "format": ".1f"} ] }

format: ".1f"控制tooltip里的数字显示一位小数，它不影响实际数据。如果你希望显示的是百分比而不是原始数值，最稳的方式是在数据源里直接加一列占比字段，让tooltip引用这个字段，省去在transform里计算百分比可能引来的各种坑。

5.4 结束前必须提的适用边界

饼图真的很挑场景。我的建议是：超过5到6个分类就不要用饼图了。一旦扇区超过8个，就会出现标签挤在一起、颜色难以区分、图例要来回扫视的问题，信息传递效率反而不如一个排序后的柱状图。除非你一定要强调"部分与整体"的关系并且分类很少，否则优先选柱状图。

6. 从能出图到好用：数据聚合、双轴组合与条件配色

6.1 双Y轴组合图：柱状图叠加折线图

搜索平台有很多人在问"柱状图叠加折线图怎么做"，这大概是图表里最经典的组合场景：柱状图展示绝对值，比如销售额；折线图展示相对值，比如同比增长率。Markvis用图层的方式就能实现：

{ "layer": [ { "data": { "values": [ {"月份": "1月", "销售额": 120, "增长率": 8}, {"月份": "2月", "销售额": 180, "增长率": 15}, {"月份": "3月", "销售额": 150, "增长率": -5}, {"月份": "4月", "销售额": 210, "增长率": 12} ] }, "mark": {"type": "bar", "cornerRadius": 3}, "encoding": { "x": {"field": "月份", "type": "ordinal", "axis": {"title": "月份"}}, "y": {"field": "销售额", "type": "quantitative", "axis": {"title": "销售额（万元）"}} } }, { "data": { "values": [ {"月份": "1月", "销售额": 120, "增长率": 8}, {"月份": "2月", "销售额": 180, "增长率": 15}, {"月份": "3月", "销售额": 150, "增长率": -5}, {"月份": "4月", "销售额": 210, "增长率": 12} ] }, "mark": {"type": "line", "stroke": "#E45756", "strokeWidth": 3}, "encoding": { "x": {"field": "月份", "type": "ordinal"}, "y": {"field": "增长率", "type": "quantitative", "axis": {"title": "同比增长率（%）", "orient": "right"}} } } ], "resolve": {"scale": {"y": "independent"}} }

两个layer共用同一个x字段，但各自的y字段不同。第二个layer的axis里orient设为right，增长率就在右侧显示自己的刻度。resolve里的scale.y.independent很关键，它让两根y轴各自独立计算刻度范围。如果不加这个配置，引擎会强行共用一套坐标，把增长率的小数值和销售额的大数值混在一起，折线基本上就贴地了。

这里必须提醒一句：双Y轴图的争议一直不小。两个物理量纲不同的轴放在一张图里，读图的人很容易被左右刻度误导。我自己的习惯是：内部数据监控板可以用，信息密度高；对外发布的正式报告尽量拆成上下两个小图，或者用"柱状图加增长率文字标注"的方式，别让读者冒读错轴的风险。

6.2 用transform做聚合：直接喂明细数据

大部分Markvis教程里的values，都是手动整理好的汇总数。但真实场景里，数据往往是明细行，比如一张订单表每行是一笔订单。Markvis在spec里支持transform字段，可以让引擎直接帮你做聚合。

假如你的数据源长这样：

{ "data": { "values": [ {"品类": "数码", "订单金额": 3200}, {"品类": "数码", "订单金额": 1800}, {"品类": "服饰", "订单金额": 950}, {"品类": "服饰", "订单金额": 1420} ] }, "transform": [ { "aggregate": [{"op": "sum", "field": "订单金额", "as": "总金额"}], "groupby": ["品类"] } ], "mark": "bar", "encoding": { "x": {"field": "品类", "type": "nominal"}, "y": {"field": "总金额", "type": "quantitative"} } }

transform里的aggregate算子会把订单金额按品类求和，生成"品类+总金额"的新字段，再交给mark和encoding去绘制。这意味着你不需要事先在Excel里做数据透视，把原始数据丢进去，让图表引擎替你完成聚合逻辑。对于周期性更新的报表，这个特性非常省力。

6.3 条件配色：高亮最高值

再进阶一点的需求：我希望柱状图里数值最高的那根柱子用突出的强调色，其余柱子用浅灰色，这样读者一眼就能锁定最大值。实现这个效果要用transform计算一个isTop字段，再用condition做条件颜色映射：

{ "data": { "values": [ {"品类": "数码", "销售额": 320}, {"品类": "服饰", "销售额": 258}, {"品类": "美妆", "销售额": 186}, {"品类": "食品", "销售额": 142} ] }, "transform": [ { "calculate": "datum.销售额 == max(datum.销售额)", "as": "isTop" } ], "mark": "bar", "encoding": { "x": {"field": "品类", "type": "nominal"}, "y": {"field": "销售额", "type": "quantitative"}, "color": { "condition": {"test": "datum.isTop", "value": "#E45756"}, "value": "#C8C8C8" } } }

condition是Vega-Lite条件编码里非常高频的用法：满足test条件的项使用前面的value，不满足的用下方兜底的value。虽然这里用到了transform里的calculate，但照着抄是完全没问题的。

6.4 交互提示：显式配置tooltip

Markvis生成的图表默认就有一定交互，但tooltip显示什么内容是值得显式配置的。不配置的情况下，引擎的默认行为不一定符合你的需求，尤其当你想要控制标题文案或者数字格式的时候。推荐在encoding里加tooltip数组：

"encoding": { "tooltip": [ {"field": "品类", "type": "nominal", "title": "品类"}, {"field": "销售额", "type": "quantitative", "title": "销售额（万元）", "format": ",.0f"} ] }

这样鼠标悬停时，只会显示品类和销售额两列信息，标题可以自定义，数字会用千分位分隔符展示。这个细节在公开的文档或博客里很重要，读者看数据时，体验是直接拉满的。

6.5 分面小多图

最后提一个能让图表显得很专业的玩法：facet分面。如果你有多个产品线的月度数据，与其挤在一张图里画成乱糟糟的多折线，不如按品类拆成小多图并列展示。Vega-Lite支持在spec里加facet：

"facet": { "column": {"field": "品类", "type": "nominal"} }

这样每个品类会生成一个独立的绘图区域，横向排开，共用同样的坐标尺度。这种"小多图"形式在做对比分析时比单张大图清晰得多，是带分析性质图表的常用手法。不过facet在Markvis里的具体表现取决于渲染器版本，建议先到在线编辑器里验证效果再放入文档。

7. 我踩过的坑：从vis块不解析到中文变方块

7.1 vis代码块不解析，页面原样输出JSON

这是最让人头疼的情况。构建之后页面上原样显示一大段JSON，意味着vis代码块根本没被插件捕获。我的排查顺序是：

1. 语言标记是否严格使用小写vis，前后不能有多余空格
2. 插件是否成功安装，跑一下npm ls hexo-markvis确认它在依赖列表里
3. 是否执行过hexo clean，有时候旧的server缓存会消耗掉新装插件
4. 检查页面源码里是否有引入markvis相关的JavaScript文件

这套顺序基本能覆盖90%的"vis不解析"问题。

7.2 JSON格式错误：尾逗号和单引号

JSON语法有两个几乎人人都犯过的毛病：对象最后一项后面多写了逗号，以及键名用了单引号。比如：

{ "x": {"field": "季度", "type": "nominal"}, "y": {"field": "销售额", "type": "quantitative"}, }

最后一个逗号在JavaScript对象里没问题，但JSON解析器会直接报错。代码块里的配置一旦解析失败，页面不会给你一个醒目的红字报错，而是直接跳过渲染，留下一片空白。解决办法只有一个：配置写完去在线编辑器粘贴验证一遍，不要依赖肉眼检查。

7.3 中文字体变成方块

在部分Hexo主题的默认样式下，SVG里的中文会渲染成方块或者干脆不显示。原因是SVG的text元素继承了页面的字体设置，有些极简主题没有声明中文字体栈。解决办法是在自定义样式里补一段：

.vis text, .vega-embed text { font-family: "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; }

如果用的是vega-embed容器，.vega-embed text这个选择器基本就能覆盖到。注意把中文字体放在sans-serif之前，优先级才会生效。

7.4 柱状图的数值标签被裁剪或者贴底

如果你的柱状图数值都比较大，并且想显示柱子顶端的数字标签，注意文本层的偏移量。dy:-8向上偏移，但标签字号大或者柱子矮的时候，文字可能被画布裁掉。我一般会把dy调到-12到-16，同时把字号降到11或12。

如果想强制y轴从0开始，在y的encoding里显式声明：

"y": { "field": "销售额", "type": "quantitative", "scale": {"zero": true} }

Vega-Lite对bar标记默认从0开始，但如果你使用了layer或者在层里改过scale的domain，最好还是显式写zero，不然容易被截断坐标误导读图的人。

7.5 字段名或type写错导致的"渲染却不对"

图表能渲染出来，但柱子顺序完全不对、折线分组错乱、饼图扇区不符合预期，大多是type写错了。我把常见的类型选择规则再理一遍：

• 品牌、品类、地区这种纯离散名字，用nominal
• 月份、星级、尺码这种有顺序但不是连续数值的，用ordinal
• 金额、人数、温度这种连续数值，用quantitative
• 标准日期时间字符串，用temporal

一个非常典型的错误：把月份字段写成quantitative，导致10月、11月、12月这几个带两位数的月份被按数字方式排序，结果整个时间轴是乱的。字段类型一旦写对，很多"莫名其妙"的问题就自动消失了。

7.6 大数据量下的SVG卡顿

当values里有几千行数据时，SVG模式下会生成大量DOM节点，页面卡顿几乎是不可避免的。这种情况建议改用Canvas渲染，在spec顶层加一个renderer字段：

{ "renderer": "canvas", "data": {}, "mark": "", "encoding": {} }

Canvas在大量图形元素的场景下性能优势非常明显，代价是失去SVG的DOM可访问性和部分CSS控制。对纯数据展示类图表来说，Canvas完全够用。

7.7 最高效的避坑习惯：先在线编辑器，再进文档

综合上面这些坑，你会发现大部分问题其实都可以在渲染之前被发现。我现在处理Markvis图表的固定流程是：先在在线编辑器里把spec跑通，确认数据、颜色、标签、图例都没问题，再把JSON原封不动粘回Markdown的vis代码块里。这样做最主要的好处是把"配置是否正确"和"Markvis是否正常工作"两个变量分开，不会出现两边混在一起，一个小问题排查好几个小时的情况。

最后说一点我的实际体会。我写博客画图很多年，以前最怕的不是画图本身，而是"数据变了"这四个字。数据一变，图表要重新生成，图片要重新上传，链接要重新核对。用Markvis之后，图表真的变成了文档的一部分，数据改动只发生在vis代码块内部，重新构建发布就完成了同步，再也不用做图片文件管理。

如果你的场景是写数据类博客、内部技术文档或者周期性周报，我建议从柱状图的案例开始，先照着配置跑通一个vis代码块，体验一下把图表直接嵌进Markdown是什么感觉。跑通之后你会有一个很明显的变化：习惯了图表随数据即时更新，就再也回不去"截图、贴图、传图床"的老流程了。如果后续在配置上踩到什么新的坑，欢迎把排查过程记录下来，可视化图表的坑大多数是相通的，你的一次排查记录很可能帮到下一个卡壳的人。