企业官网建设流程全解析

最近在维护一个老项目，HTML 文件里一个标签的 className、data-* 属性排了一长串。我按Ctrl+S保存，瞬间整个标签被拆成六七行，属性一个占一行，屏幕直接变三倍长。旁边同事还补了一句：这不是很整齐吗？我当时很想把机箱扔过去——对齐是整齐了，可一个 30 行的文件变成 180 行，Git 上的 diff 全是无关改动，我还怎么 review？

后来我发现，这个问题在 VSCode 里非常典型：只要开了保存时自动格式化，又同时装过 Prettier、Vetur、内置 HTML 格式化器中的一个或几个，“标签属性自动换行”就会以各种形态出现。这篇博客就是要把 VSCode 保存时标签属性自动换行这件事彻底讲清楚，从根因到配置，给你一套能直接落地的解决方案。

1. 问题本质：谁在你保存时偷偷改了格式？

1.1 保存即格式化，这是设计好的流程

VSCode 里有一个所有人都可能不小心打开的开关：editor.formatOnSave。它一开，你每次Ctrl+S，编辑器都会把当前文件交给注册好的“格式化器”重新排版一遍。排版当然是好事，统一缩进、统一换行、统一引号风格，能省掉大量手动调整。但它也会带来副作用——格式化器有一套自己的“审美偏好”，其中就包括 HTML 标签属性该不该换行。

我用一个非常简单的例子说明：假设你有这样一行代码：

<button type="button" class="btn btn-primary"><button type="button" class="btn btn-primary" >{ "editor.formatOnSave": true, "html.format.wrapAttributes": "preserve", "html.format.wrapLineLength": 200 }

几个取值的效果我帮大家列一下：

我最推荐日常开发用preserve或auto。preserve的意思是“你原本怎么写，我就怎么保留”，保存时不会强行拆开你写好的标签；auto则给了格式化器一个兜底：如果一行太长，偶尔拆一下，避免横向滚动。

wrapLineLength也要顺带提一下。它是内置格式化器的行宽阈值，默认 120。当wrapAttributes为auto时，如果一行宽度超过这个值，格式化器还是会拆行。你把它调大到 200 甚至更高，能让绝大多数标签保持一行。

3.2 场景二：Prettier 接管格式化（团队项目最常见）

大部分现代前端项目都会装 Prettier。Prettier 是一个“固执己见”的格式化器，它对属性换行的控制方式和内置格式化器完全不同，你设置里再改html.format.wrapAttributes都没用，因为它根本不读这个字段。

Prettier 影响属性换行的主要有三个配置：

第一个是singleAttributePerLine。它默认false。但如果项目配置里被设成了true，Prettier 会把每个 HTML 属性强制放到单独一行——这就是很多“标签属性自动换行”的直接元凶。解决方法是把它改成false：

{ "singleAttributePerLine": false }

注意，这个选项在 Prettier 2.6 之后才支持。如果你用的老版本 Prettier，升级扩展或加装新版 Prettier 后再用。

第二个是printWidth。这是 Prettier 的“行宽预算”，默认 80。只要一行代码折算出来的字符宽度超过 80，Prettier 就会在合适的断点换行，而标签属性之间的空格就是一个非常合适的断点。所以一个标签如果属性较多，特别容易触发换行。你可以把printWidth调大，比如 120：

{ "printWidth": 120, "singleAttributePerLine": false }

这样宽度不超过 120 的标签都会保持在一行。但要注意，printWidth影响的是整个文件，不只是 HTML。JS 对象、函数参数也会跟着放宽，团队如果已有规范，需要统一评估。

第三个是htmlWhitespaceSensitivity。它决定 Prettier 对 HTML 空白符的敏感程度，可选值css、strict、ignore。默认是css，意思是“根据 CSS display 属性决定空白是否重要”。有时候你会遇到“属性明明没超宽度，还是被拆行”的情况，可能就是htmlWhitespaceSensitivity设置为strict导致的，因为 strict 会尽量保留原始空白结构，反而触发了更保守的换行策略。

我实测下来，对绝大多数页面，设置为ignore能最大程度减少标签属性换行：

{ "htmlWhitespaceSensitivity": "ignore", "printWidth": 120, "singleAttributePerLine": false }

但这里要提醒一句：ignore会弱化对 HTML 中空格差异的感知。如果页面里有inline-block元素、<span>之间靠空格分隔、或必须依赖源码空格的场景，改成ignore后可能造成渲染上的细微变化。稳妥做法是先小范围试一个文件，确认视觉无异常再全量用。

Prettier 的配置放在哪？推荐在项目根目录建一个.prettierrc文件，内容用 JSON 格式：

{ "printWidth": 120, "htmlWhitespaceSensitivity": "ignore", "singleAttributePerLine": false }

同时确认 VSCode 的默认格式化器是 Prettier：

{ "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.formatOnSave": true }

这样保存时，HTML 文件会走 Prettier 规则，属性换行行为由.prettierrc控制。

3.3 场景三：.vue 文件里的标签属性换行

Vue 项目的.vue文件比较特殊，它有<template>、<script>、<style>三个区块，不同区块可能由不同格式化器负责。如果你在普通.html文件里改了设置，但.vue文件保存后标签属性依然自动换行，多半是 Vue 插件在捣乱。

老项目用 Vetur 的话，控制 HTML 模板格式化的是vetur.format.defaultFormatter.html。它可以设置为prettyhtml或prettier。如果你希望模板里的标签属性不强制换行，可以这样配置：

{ "vetur.format.defaultFormatter.html": "prettyhtml", "vetur.format.defaultFormatterOptions": { "prettyhtml": { "wrapAttributes": false } } }

也可以直接把 HTML 格式化器换成 Prettier，然后沿用上一节的 Prettier 配置：

{ "vetur.format.defaultFormatter.html": "prettier" }

新项目如果用的是 Volar（官方现在主推的 Vue 语言工具），它本身会尊重 Prettier 配置，所以你在项目根目录放好.prettierrc，然后保证editor.defaultFormatter是 Prettier 即可。Volar 对 HTML 模板的格式化实际是调用 Prettier 来完成的，不需要额外设置。

这里有个很容易踩的坑：一个项目同时装了 Vetur 和 Volar，两个扩展都会注册自己的格式化能力，VSCode 可能会在保存弹窗里问你“要使用哪个扩展进行格式化”，如果选错，后面所有配置都会错位。建议只保留其中一个，旧项目用 Vetur，新项目统一用 Volar。

3.4 场景四：局部不想换行？用注释强制锁定

配置是全局的，但有时候你只是想让某个特别长的标签保持一行，不想为它单独改配置文件。这种情况可以用格式化器的“忽略注释”来局部锁定。

• 内置格式化器：没有标准的 ignore 注释可用，最省事的办法是把该标签的 class、style 写紧凑点，或者临时把wrapAttributes改为preserve。不过内置格式化器支持html.format.unformatted设置，你可以把某个标签加入“不格式化”列表，但它影响的是标签内部内容，不是属性换行。
• Prettier：提供了明确的范围忽略语法。在 HTML 里，这样写：

<!-- prettier-ignore --> <div class="important"><!-- prettier-ignore-start --> <div class="a">{ "editor.formatOnSave": true, "editor.defaultFormatter": "vscode.html-language-features", "html.format.enable": true, "html.format.wrapAttributes": "preserve", "html.format.wrapLineLength": 200, "html.format.maxPreserveNewLines": 2, "html.format.extraLiners": "" }

逐行解释一下：

• editor.formatOnSave：保存时自动格式化，这是触发场景，必须确认它是true才能复现你的问题；设为false也能解决换行，但我不建议这么做，因为格式化功能本身有它的价值。
• editor.defaultFormatter：指定默认格式化器为 VSCode 内置的 HTML Language Features，避免被 Prettier 抢走。
• html.format.enable：确认内置 HTML 格式化启用。
• html.format.wrapAttributes：设为preserve，核心就是这一项。
• html.format.wrapLineLength：行宽阈值调大到 200，即使wrapAttributes是auto也能显著减少换行。
• html.format.maxPreserveNewLines：格式化后最多保留的连续空行数，设 2 是为了让页面紧凑一些。
• html.format.extraLiners：默认会在<head>、<body>前添加额外换行，设空字符串可以避免这种多余空行，让文件更紧凑。

这个配置用在维护老页面、看历史 diff 的场景下很舒服，文件改动量小，不会因为一次保存制造出一大堆无意义 diff。

4.2 .prettierrc 推荐配置（Prettier 方案）

如果你在团队项目里，Prettier 基本是标配，那就不要折腾内置格式化了，直接在项目根目录建一个.prettierrc文件，内容如下：

{ "printWidth": 120, "tabWidth": 2, "useTabs": false, "semi": true, "singleQuote": true, "htmlWhitespaceSensitivity": "ignore", "singleAttributePerLine": false, "proseWrap": "preserve", "endOfLine": "auto" }

其中和属性换行直接相关的就是三行：printWidth、htmlWhitespaceSensitivity、singleAttributePerLine。其他是团队常规风格，你可以按需删减。

然后确认 VSCode 侧配置：

{ "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode" }

再强调一次：如果项目里已有.prettierrc，VSCode 里prettier.*的设置会被项目配置覆盖。所以别在settings.json里反复改prettier.printWidth却看不到效果，先检查项目根目录有没有.prettierrc或prettier.config.js。

4.3 项目级配置与团队统一

我个人非常推荐把格式化配置放进项目根目录，而不是只改用户级settings.json。原因是：格式化本质是团队协作规范的一部分，只在你本机生效，队友那边照样会换行，Git 提交后还是一堆冲突。

项目级的配置路径有两个：

• .vscode/settings.json：只对这个项目生效，会被 Git 提交，适合放editor.defaultFormatter、html.format.wrapAttributes这类编辑器行为。
• .prettierrc：Prettier 的项目级配置文件，适合放代码风格规则。

举个例子，项目里可以这样组织：

my-project/ ├── .vscode/ │ └── settings.json ├── .prettierrc └── src/ └── index.html

.vscode/settings.json里填：

{ "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.formatOnSave": true }

.prettierrc里按上一节填。这样不管谁来克隆项目，只要装了 Prettier 扩展，保存时行为完全一致。如果有人没装 Prettier，VSCode 也会提示安装推荐扩展。如果想让体验更进一步，还可以在.vscode/extensions.json里声明推荐的扩展 ID，让队友打开项目时直接被推荐安装。

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

5.1 速查表：症状、原因、处理方式

我把平时被问得最多的情况整理成了一张表，照着查就行：

5.2 我踩过的三个坑

第一个坑：在 settings.json 里设置了html.format.wrapAttributes: "force"后忘了删，几个月后格式化 HTML 都是“拆拆拆”。有一次我怀疑是 Prettier 的问题，反复调printWidth，浪费了大半天。后来才发现是早期为了某些页面特意把属性拆开看的，设置一直留在用户级配置里。这个配置藏得深，因为它在html.format组下面，搜索“wrap”很容易忽略。建议所有 HTML 格式化设置最好放在项目级.vscode/settings.json，避免污染全局。

第二个坑：Vetur 和 Volar 同时装，保存 .vue 文件时弹窗选错，导致模板被 prettyhtml 强制拆行。当时项目的.prettierrc已经写了singleAttributePerLine: false，但 Vetur 不走 Prettier 的 HTML 模板格式化，而是走 prettyhtml，所以我的 Prettier 配置完全无效。最后卸载 Vetur、只保留 Volar，问题立刻消失。如果你还在维护老项目，先确认是哪个插件在格式化模板，再针对配置。

第三个坑：htmlWhitespaceSensitivity: "ignore"导致行内元素之间的空格被压缩。页面里有一串<span>价格</span> <span>￥99</span>，原本中间有个空格，格式化后空格没了，价格直接黏在一起。这类问题在视觉上很隐蔽，容易上线后才被发现。后来我改用"css"默认值，虽然换行会多一些，但至少不会破坏排版。如果你一定要用ignore，建议在配置后人工检查一下行内元素密集的区域。

5.3 保存时还想保留格式化，但不想让“它”动我的标签，怎么办？

如果你既想享受格式化带来的统一缩进、引号风格，又不想让标签属性被拆行，我的建议是：

1. 用 Prettier，设置printWidth: 140、htmlWhitespaceSensitivity: "css"、singleAttributePerLine: false。
2. 对极少数超长的标签，用<!-- prettier-ignore -->锁定。
3. 保持editor.formatOnSave: true，但把editor.defaultFormatter固定成 Prettier，避免多个格式化器来回争夺。

这套组合我在实际项目里用了很久，既能保证大部分代码风格统一，又不会因为属性换行制造大量无意义 diff。如果你只想解决手头这个“保存后属性自动换行”的眼前问题，最快的方案其实是：打开settings.json，全局搜一下wrapAttributes，如果是force改成preserve，然后看editor.defaultFormatter是不是 Prettier，如果是就检查.prettierrc里的两个开关。五步之内基本解决。

最后再分享一个我自己的工作习惯：我在编辑器里永远把“格式化文档”这个动作和“保存”解耦。具体做法是，editor.formatOnSave设置为true，但editor.formatOnPaste和editor.formatOnType关掉，同时把默认格式化器固定为 Prettier。这样保存时只有它一个角色在管排版，所有换行规则都去.prettierrc里找，排查问题只需要看一个文件。这个习惯帮我少踩了很多格式化冲突的坑。你如果现在还在被标签属性换行折腾，不妨也试试这个思路——先统一格式化器，再谈配置，问题往往就迎刃而解了。