--- URL: "/zh-CN/blog/2026-02/vue-comment.html" LLMS_URL: "/zh-CN/blog/2026-02/vue-comment.md" lastUpdated: true commentabled: true recommended: true title: "Vue 模板中保留 HTML 注释的完整指南" description: "Vue 模板中保留 HTML 注释的完整指南" date: pageClass: "blog-page-class" cover: "/covers/vue.svg" --- --- lastUpdated: true commentabled: true recommended: true title: Vue 模板中保留 HTML 注释的完整指南 description: Vue 模板中保留 HTML 注释的完整指南 date: 2026-02-14 13:45:00 pageClass: blog-page-class cover: /covers/vue.svg --- ## 前言：注释的艺术 ## 在 Vue 开发中，我们经常需要在模板中添加注释。这些注释可能是： - 📝 开发者备注：解释复杂逻辑 - 🏷️ 代码标记：TODO、FIXME 等 - 🔧 模板占位符：为后续开发留位置 - 📄 文档生成：自动生成 API 文档 - 🎨 设计系统标注：设计意图说明 但是，你可能会发现 Vue 默认会*移除*模板中的所有 HTML 注释！今天我们就来深入探讨如何在 Vue 中保留这些有价值的注释。 ## 一、Vue 默认行为：为什么移除注释？ ## ### 源码视角 ### ```javascript // 简化版 Vue 编译器处理 function compile(template) { // 默认情况下，注释节点会被移除 const ast = parse(template, { comments: false // 默认不保留注释 }) // 生产环境优化：移除所有注释 if (process.env.NODE_ENV === 'production') { removeComments(ast) } } ``` Vue 移除注释的原因： - 性能优化：减少 DOM 节点数量 - 安全性：避免潜在的信息泄露 - 代码精简：减少最终文件体积 - 标准做法：与主流框架保持一致 ### 默认行为演示 ### ```vue ``` 编译结果： ```html

Hello World

John Doe
``` 所有注释都不见了！ ## 二、配置 Vue 保留注释的 4 种方法 ## ### Vue 编译器配置（全局） ### Vue 2 配置 ```javascript:vue.config.js module.exports = { chainWebpack: config => { config.module .rule('vue') .use('vue-loader') .tap(options => { return { ...options, compilerOptions: { comments: true // 保留注释 } } }) } } ``` ```js:webpack.config.js module.exports = { module: { rules: [ { test: /\.vue$/, loader: 'vue-loader', options: { compilerOptions: { comments: true } } } ] } } ``` Vue 3 配置 ```javascript:vite.config.js import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [ vue({ template: { compilerOptions: { comments: true // 保留注释 } } }) ] }) ``` ```js:vue.config.js // (Vue CLI) module.exports = { configureWebpack: { module: { rules: [ { test: /\.vue$/, use: [ { loader: 'vue-loader', options: { compilerOptions: { comments: true } } } ] } ] } } } ``` ### 单文件组件配置（Vue 3 特有） ### ```vue ``` ### 运行时编译（仅开发环境） ### ```javascript // 使用完整版 Vue（包含编译器） import Vue from 'vue/dist/vue.esm.js' new Vue({ el: '#app', template: `

Hello

`, compilerOptions: { comments: true } }) ``` ### 使用 ` ``` ## 三、注释的最佳实践与用例 ## ### 组件文档生成 ### ```vue ``` ### 设计系统标注 ### ```vue ``` ### 协作开发标记 ### ```vue ``` ## 四、环境差异化配置 ## ### 开发环境 vs 生产环境 ### ```javascript:vue.config.js module.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 } }) } } ``` ### 按需保留特定类型注释 ### ```javascript // 自定义注释处理器 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) } } }) } } ``` ## 五、高级用法：注释数据处理 ## ### 自动提取 API 文档 ### ```vue ``` ```javascript // 注释提取脚本 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 traverseAST(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)) ``` ### 代码质量检查 ### ```javascript // eslint-plugin-vue-comments module.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 ### ```javascript // 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 注释 ### ```jsx // 自定义注释组件 const Comment = ({ text }) => (