正文

Markdown代码块缩进报错显示乱码怎么办这篇教程用真实案例手把手教你正确写法

/0 浏览量
0903

Markdown代码块缩进报错显示乱码怎么办

今天咱们来聊聊一个让不少人都头疼的小问题——Markdown里代码块的缩进和乱码。别看这是个”小问题”，真到了写文档的时候，搞不好能把人整得怀疑人生。

我之前帮一个做技术博客的朋友改过一篇文章，他发给我看的时候，代码块那边全乱套了，缩进不对、中文显示乱码，他自己都看懵了。后来我们一点点排查，发现根源其实就那么几处。今天我把这些坑都给你捋清楚，保准你看完之后不会再踩这些雷。

先搞清楚：你的代码块到底是哪种写法

Markdown写代码块，主要就两种路子。一种是缩进式，另一种是围栏式。这两种写法搞混了，就是乱码的罪魁祸首。

围栏式写法（推荐）

这是现在最主流的写法，用三个反引号 ` 把代码包起来：

```
function hello() {
  console.log("你好");
}
```

注意看，开头的 后面可以跟语言名，比如javascript 、python 、markdown 这样，这样还能触发语法高亮，效果特别好。

缩进式写法

这种是早期Markdown的写法，需要在代码前面加四个空格或者一个Tab：

    function hello() {
      console.log("你好");
    }

你看，每一行都要缩进四个空格。问题来了——很多人会在这里栽跟头。

坑一：两种写法混着用

我见过最多的一类问题，就是有人一会儿用围栏式，一会儿用缩进式，最后编辑器直接懵了。

举个真实的例子：

```javascript
function test() {
    console.log("测试");
    }

function another() {
    console.log("另一个");
}


上面这段代码，第一块用了围栏式，第二块用了缩进式。如果在某些Markdown渲染器里，第二块的缩进可能会被视为代码的一部分，导致多余的空白出现。

**正确做法**：选一种方式，全程坚持用下去。我强烈建议用围栏式，因为更直观、更好维护，也不会被缩进问题搞死。

## 坑二：缩进空格数不对

缩进式代码块要求**每行都缩进至少四个空格或一个Tab**。但很多人会犯这样的错误：

```markdown
代码块内容
    第一行缩进了四个空格
  第二行只缩进了两个空格   ← 这里出问题了
    第三行又对了

第二行只缩进了两个空格，在某些渲染器里，这一行可能就不被识别为代码块内容，而是当作普通文本显示，格式瞬间就乱套了。

正确做法：要么统一用四个空格，要么统一用Tab。别混用，空格和Tab混在一起的时候，不同编辑器显示效果不一样，你在这里看着正常，别人那里可能就崩了。

坑三：代码块内部又缩进了

这是最容易被忽视的一个坑。有人觉得代码块里面的代码也需要再缩进，就写成这样：

```javascript
    function hello() {
        console.log("你好");
    }
```

代码块内部的每一行前面又多套了四个空格。这本身不会报错，但如果你的代码本身就有缩进，比如JavaScript的函数体：

```javascript
    function hello() {
        console.log("你好");
            if (true) {
                console.log("嵌套更深了");
            }
    }
```

这样渲染出来的效果是，每一行都多了四个空格的基准偏移量，代码看起来全往右跑了一大截，阅读体验极差。

正确做法：围栏式代码块不需要在代码前额外加缩进。直接写代码就行：

```javascript
function hello() {
    console.log("你好");
    if (true) {
        console.log("嵌套更深了");
    }
}
```

代码本身的缩进保留即可，不需要再在外面套一层。

坑四：编码问题导致的乱码

这个跟缩进不是一回事，但经常跟缩进问题一起来，让人傻傻分不清楚。

乱码的典型表现是中文变成一堆问号或者奇怪的符号，比如：

function test() {
    console.log("浣犲ソ");
}

出现这种情况，100%是编码问题。你的Markdown文件可能保存成了GBK或者别的不支持中文的编码格式，而渲染器期望的是UTF-8。

排查方法：

用你手头的编辑器打开文件，查看编码格式。VS Code右下角会显示当前文件的编码，Typora可以在”文件”菜单里看到。确保文件是 UTF-8 编码。

如果是用命令行工具或者脚本处理的，也要确保整个链路都是UTF-8：

# 检查文件编码
file -i yourfile.md

# 如果是GBK，转成UTF-8
iconv -f GBK -t UTF-8 yourfile.md > yourfile_utf8.md

真实案例：有个读者反馈，他在Windows上用记事本写了个Markdown文件，里面全是中文代码注释。保存到一半，注释全乱码了。问他用什么保存的，他说”记事本默认不就是UTF-8吗”。我说你打开记事本，点”文件→另存为”，右下角编码选项选的是”ANSI”而不是”UTF-8”。换成UTF-8保存，问题立马解决。

坑五：特殊字符没转义

代码块里如果有反引号、#、$这些特殊字符，有时候也会闹出乱码的假象。

比如你在Markdown里写：

```
这是三个反引号：```
```

有些渲染器可能解析出错了，因为它看到代码块内部出现了 “` ，可能会误以为代码块结束了。

正确做法：如果代码块内部需要出现 “` ，就在外面用四个反引号包起来：

这是三个反引号：```

这样渲染器就知道外层四个反引号才是代码块的边界，内部的三个反引号就是普通文本。

坑六：Tab和空格的视觉差异

这个坑非常隐蔽。有些人为了代码整齐，用了Tab缩进，有些人用了空格缩进。Tab在Markdown编辑器里可能显示为4个空格，也可能显示为8个空格，取决于你的编辑器设置。

比如这段代码：

function test() {
	tab缩进		← 一个Tab
	    四个空格缩进	← 四个空格
	tab+空格		← Tab加两个空格
}

你在本地看着好像对齐了，但发布之后到别人的设备上看，可能就全歪了。因为不同渲染器的Tab宽度不一样。

正确做法：代码里统一用空格，不要用Tab。现在主流的语言风格和编辑器配置都推荐用空格缩进，两个空格或者四个空格都可以，但全篇统一。

完整示例：一个没问题的Markdown代码块

把上面说的这些要点综合起来，一个正确的代码块长这样：

# JavaScript基础

下面是一个简单的函数示例：

```javascript
// 这是一个注释，里面可以有中文：你好，世界
function greet(name) {
    // 四个空格缩进，不用Tab
    const message = "你好，" + name;
    
    if (name) {
        console.log(message);
        // 嵌套代码也保持统一的四个空格
        return true;
    }
    
    return false;
}

// 如果代码里需要出现 ``` 这样的字符，用四个反引号包裹外层
console.log(greet("小明"));
```

上面代码保存为UTF-8编码，用围栏式写法，统一四个空格缩进，中文正常显示，没有任何乱码问题。

常见编辑器的设置建议

最后给你几个常用编辑器的建议，帮你从源头上避免这些问题：

VS Code：

  • 打开设置，搜索 editor.tabSize，设为 4
  • 搜索 editor.insertSpaces，设为 true（用空格不用Tab）
  • 右下角点击编码，确认是 UTF-8
  • 搜索 editor.trimWhitespace，设为 true，避免行尾多余空格

Typora：

  • 文件→文档设置，确认编码为UTF-8
  • 偏好设置→编辑，可以调整代码块的缩进样式

Obsidian：

  • 设置→编辑器→代码块，可以设置代码块内默认的缩进方式
  • 确保编辑的文件编码为UTF-8

总结一下

Markdown代码块缩进报错、显示乱码，基本上就是这几个原因：

  1. 围栏式和缩进式混用 → 选一种，推荐围栏式
  2. 缩进空格数不够四格 → 每行统一四个空格
  3. 代码块内额外套缩进 → 直接写代码，不需要外层再缩进
  4. 文件编码不是UTF-8 → 检查并转换为UTF-8
  5. 特殊字符没处理好 → 反引号多了就多加一层
  6. Tab和空格混用 → 统一用空格，别用Tab

你下次写Markdown之前，先把编码确认好，然后全程用围栏式写法，代码里用空格缩进，基本上就不会再出问题了。要是还是不行，把文件贴到在线的Markdown预览器里验证一下，比如 markdownlivepreview.com，那边渲染对了，基本就稳了。

有问题随时来聊，写文档这事儿，踩坑是正常的，多试几次就熟了。

-- 展开阅读全文 --