前言：注释的艺术

在 Vue 开发中，我们经常需要在模板中添加注释。这些注释可能是：

• 开发者备注：解释复杂逻辑
• 代码标记：TODO、FIXME 等
• 模板占位符：为后续开发留位置
• 文档生成：自动生成 API 文档
• 设计系统标注：设计意图说明

但问题来了——Vue 默认会把模板中的所有 HTML 注释统统移除。这显然不是我们想要的。那么，怎么让这些注释“活下来”呢？下面就来拆解这个问题。

一、Vue 默认行为：为什么移除注释？

源码视角

// 简化版 Vue 编译器处理function compile(template) {  // 默认情况下，注释节点会被移除  const ast = parse(template, {    comments: false // 默认不保留注释  })    // 生产环境优化：移除所有注释  if (process.env.NODE_ENV === 'production') {    removeComments(ast)  }}

Vue 移除注释的原因：

1. 性能优化：减少 DOM 节点数量
2. 安全性：避免潜在的信息泄露
3. 代码精简：减少最终文件体积
4. 标准做法：与主流框架保持一致

默认行为演示

编译结果：

  
Hello World
  
    John Doe  

所有注释都不见了！

二、配置 Vue 保留注释的 4 种方法

方法1：Vue 编译器配置（全局）

Vue 2 配置

// vue.config.jsmodule.exports = {  chainWebpack: config => {    config.module      .rule('vue')      .use('vue-loader')      .tap(options => {        return {          ...options,          compilerOptions: {            comments: true // 保留注释          }        }      })  }}// 或 webpack.config.jsmodule.exports = {  module: {    rules: [      {        test: /\.vue$/,        loader: 'vue-loader',        options: {          compilerOptions: {            comments: true          }        }      }    ]  }}

Vue 3 配置

// vite.config.jsimport { defineConfig } from 'vite'import vue from '@vitejs/plugin-vue'export default defineConfig({  plugins: [    vue({      template: {        compilerOptions: {          comments: true // 保留注释        }      }    })  ]})// 或 vue.config.js (Vue CLI)module.exports = {  configureWebpack: {    module: {      rules: [        {          test: /\.vue$/,          use: [            {              loader: 'vue-loader',              options: {                compilerOptions: {                  comments: true                }              }            }          ]        }      ]    }  }}

方法2：单文件组件配置（Vue 3 特有）

方法3：运行时编译（仅开发环境）

// 使用完整版 Vue（包含编译器）import Vue from 'vue/dist/vue.esm.js'new Vue({  el: '#app',  template: `    
            
Hello
    
  `,  compilerOptions: {    comments: true  }})

方法4：使用

三、注释的最佳实践与用例

用例1：组件文档生成

用例2：设计系统标注

用例3：协作开发标记

四、环境差异化配置

开发环境 vs 生产环境

// vue.config.jsmodule.exports = {  chainWebpack: config => {    config.module      .rule('vue')      .use('vue-loader')      .tap(options => {        const compilerOptions = {          ...options.compilerOptions        }                // 只在开发环境保留注释        if (process.env.NODE_ENV === 'development') {          compilerOptions.comments = true        } else {          compilerOptions.comments = false        }                return {          ...options,          compilerOptions        }      })  }}

按需保留特定类型注释

// 自定义注释处理器const commentPreserver = {  // 只保留特定前缀的注释  shouldPreserveComment(comment) {    const preservedPrefixes = [      'TODO:',      'FIXME:',       'HACK:',      'OPTIMIZE:',      '@design-system',      '@api'    ]        return preservedPrefixes.some(prefix =>       comment.trim().startsWith(prefix)    )  }}// 在配置中使用module.exports = {  chainWebpack: config => {    config.module      .rule('vue')      .use('vue-loader')      .tap(options => {        return {          ...options,          compilerOptions: {            whitespace: 'preserve',            // 自定义注释处理            comments: (comment) => commentPreserver.shouldPreserveComment(comment)          }        }      })  }}

五、高级用法：注释数据处理

用例1：自动提取 API 文档

// 注释提取脚本const fs = require('fs')const path = require('path')const parser = require('@vue/compiler-sfc')function extractCommentsFromVue(filePath) {  const content = fs.readFileSync(filePath, 'utf-8')  const { descriptor } = parser.parse(content)    const comments = []  const template = descriptor.template    if (template) {    // 解析模板中的注释    const ast = parser.compile(template.content, {      comments: true    }).ast        tra verseAST(ast, (node) => {      if (node.type === 3 && node.isComment) {        comments.push({          content: node.content,          line: node.loc.start.line,          file: path.basename(filePath)        })      }    })  }    return comments}// 生成文档const componentComments = extractCommentsFromVue('./UserProfile.vue')console.log(JSON.stringify(componentComments, null, 2))

用例2：代码质量检查

// eslint-plugin-vue-commentsmodule.exports = {  rules: {    'require-todo-comment': {      create(context) {        return {          'VElement'(node) {            const comments = context.getSourceCode()              .getAllComments()              .filter(comment => comment.type === 'HTML')                        // 检查是否有 TODO 注释            const hasTodo = comments.some(comment =>               comment.value.includes('TODO:')            )                        if (!hasTodo && node.rawName === 'div') {              context.report({                node,                message: '复杂 div 元素需要添加 TODO 注释说明'              })            }          }        }      }    }  }}

六、与 JSX/渲染函数的对比

Vue 模板 vs JSX

// Vue 模板（支持 HTML 注释）const template = `  
        
Title
  
`// JSX（使用 JS 注释）const jsx = (  
    {/* JSX 中的注释 */}    
Title
    {      // 也可以使用单行注释    }  
)// Vue 渲染函数export default {  render(h) {    // 渲染函数中无法添加 HTML 注释    // 只能使用 JS 注释，但不会出现在 DOM 中    return h('div', [      // 这是一个 JS 注释，不会出现在 DOM 中      h('h1', 'Title')    ])  }}

在 JSX 中模拟 HTML 注释

// 自定义注释组件const Comment = ({ text }) => (  
)// 使用const Component = () => (  
        
内容
  
)

七、注意事项与常见问题

问题1：性能影响

// 保留大量注释的性能测试const testData = {  withComments: `    
      ${Array(1000).fill().map((_, i) =>         `\n
Item ${i}
`      ).join('\n')}    
  `,  withoutComments: `    
      ${Array(1000).fill().map((_, i) =>         `
Item ${i}
`      ).join('\n')}    
  `}// 测试结果// 有注释：虚拟DOM节点数 2000// 无注释：虚拟DOM节点数 1000// 内存占用增加约 30-50%

建议：只在开发环境保留注释，生产环境移除。

问题2：安全性考虑

问题3：SSR（服务端渲染）兼容性

// server.jsconst Vue = require('vue')const renderer = require('@vue/server-renderer')const app = new Vue({  template: `    
            
服务端渲染
    
  `})// SSR 渲染const html = await renderer.renderToString(app, {  // 需要显式启用注释  template: {    compilerOptions: {      comments: true    }  }})console.log(html)// 输出：
服务端渲染

八、最佳实践总结

配置文件模板

// vue.config.js - 完整配置示例module.exports = {  chainWebpack: config => {    // Vue 文件处理    config.module      .rule('vue')      .use('vue-loader')      .tap(options => {        const isDevelopment = process.env.NODE_ENV === 'development'        const isProduction = process.env.NODE_ENV === 'production'                return {          ...options,          compilerOptions: {            // 开发环境：保留所有注释            // 生产环境：移除注释，或只保留特定注释            comments: isDevelopment ? true : (comment) => {              const importantPrefixes = [                'TODO:',                'FIXME:',                '@design-system',                '@api-docs'              ]                            return importantPrefixes.some(prefix =>                 comment.trim().startsWith(prefix)              )            },                        // 其他编译选项            whitespace: isProduction ? 'condense' : 'preserve',            delimiters: ['{{', '}}']          }        }      })  }}

注释编写规范

各场景推荐方案

总结

在 Vue 中保留 HTML 注释需要明确的配置，但这对于开发效率、团队协作、文档维护都大有裨益。关键点：

1. 理解默认行为：Vue 为性能优化默认移除注释
2. 按需配置：根据环境选择是否保留注释
3. 规范注释：制定团队统一的注释规范
4. 考虑性能：生产环境谨慎保留注释
5. 探索高级用法：注释可以用于文档生成、代码分析等

记住：好的注释是代码的路标，而不仅仅是装饰。合理配置和使用注释，能让你的 Vue 项目更加可维护、可协作。