title: Nuxt.js 应用中的 vite：extendConfig 事件钩子
date: 2024/11/16
updated: 2024/11/16
author:
cmdragon

excerpt:
通过合理使用 vite:extendConfig 钩子，开发者可以极大地增强 Nuxt 3 项目的灵活性和功能性，为不同的项目需求量身定制 Vite 配置。无论是添加插件、调整构建选项还是配置开发服务器，这些扩展可以有效提升开发体验和应用性能。

categories:

• 前端开发

tags:

• Nuxt
• Vite
• 配置
• 钩子
• 插件
• 构建
• 环境

扫描
二维码
关注或者微信搜一搜：
编程智域 前端至全栈交流与成长

在 Nuxt 3 中，
vite:extendConfig
钩子允许开发者扩展默认的 Vite 配置。这意味着你可以在 Nuxt 项目中根据需求自定义 Vite 的配置，包括添加插件、修改构建选项、调整开发服务器设置等。

文章大纲

1. 定义与作用
2. 调用时机
3. 参数说明
4. 示例用法
5. 应用场景
   
   • 5.1 添加 Vite 插件
   • 5.2 调整构建配置
   • 5.3 自定义开发服务器设置
   • 5.4 根据环境动态调整配置
6. 注意事项
7. 总结

1. 定义与作用

• vite:extendConfig
  是一个事件钩子，提供了机会来修改 Vite 的配置对象。
• 通过该钩子，你可以将额外的 Vite 插件、构建选项、开发服务器设置等添加到项目中。

2. 调用时机

vite:extendConfig
钩子在 Nuxt 3 启动时进行 Vite 配置的构建阶段被调用，此时你可以访问到
viteInlineConfig
和环境变量
env
。

3. 参数说明

钩子接收两个参数：

1. viteInlineConfig
   : 当前 Vite 的配置对象。你可以直接修改这个对象的属性。
2. env
   : 当前的环境变量。可以根据不同环境配置。

4. 示例用法

下面是如何使用
vite:extendConfig
钩子的基本示例，展示了如何扩展 Vite 的默认配置。

在
plugins/viteExtendConfig.js
文件中的实现

// plugins/viteExtendConfig.js

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hooks('vite:extendConfig', (viteInlineConfig, env) => {
    // 添加自定义的 Vite 插件，例如 React 支持
    viteInlineConfig.plugins.push(require('@vitejs/plugin-react')());

    // 根据环境动态调整构建选项
    viteInlineConfig.build = {
      ...viteInlineConfig.build,
      sourcemap: env.NODE_ENV === 'development', // 仅在开发模式下开启 sourcemap
    };

    // 修改开发服务器设置
    viteInlineConfig.server = {
      ...viteInlineConfig.server,
      port: 3001, // 将开发服务器的端口修改为 3001
    };
  });
});

5. 应用场景

5.1 添加 Vite 插件

在涉及到使用特定功能的情况下，例如使用 React，你可以在
vite:extendConfig
中添加 Vite 插件：

// plugins/viteExtendConfig.js
viteInlineConfig.plugins.push(require('@vitejs/plugin-react')());

5.2 调整构建配置

在不同的环境中，可能需要不同的构建选项。例如，调试开发环境可以开启源码映射：

// 根据环境动态调整构建选项
viteInlineConfig.build = {
  ...viteInlineConfig.build,
  sourcemap: env.NODE_ENV === 'development', // 开发环境开启 sourcemap
};

5.3 自定义开发服务器设置

如果你需要指定开发服务器的端口，可以这样做：

// 修改开发服务器设置
viteInlineConfig.server = {
  ...viteInlineConfig.server,
  port: 3001, // 设置开发服务器端口
};

5.4 根据环境动态调整配置

使用
env
参数，可以在生产环境和开发环境中使用不同的配置。这使得你的应用更加灵活：

if (env.NODE_ENV === 'production') {
  viteInlineConfig.base = '/my-production-base/';
} else {
  viteInlineConfig.base = '/';
}

6. 注意事项

• 性能影响
  : 添加过多插件或配置可能会影响构建性能，需谨慎选择。
• 兼容性
  : 确保你所添加的插件与 Vite 及其他 Nuxt 插件兼容，以避免运行时错误。

7. 总结

通过合理使用
vite:extendConfig
钩子，开发者可以极大地增强 Nuxt 3 项目的灵活性和功能性，为不同的项目需求量身定制 Vite 配置。无论是添加插件、调整构建选项还是配置开发服务器，这些扩展可以有效提升开发体验和应用性能。

余下文章内容请点击跳转至 个人博客页面 或者 扫码关注或者微信搜一搜：
编程智域 前端至全栈交流与成长
，阅读完整的文章：
Nuxt.js 应用中的 vite：extendConfig 事件钩子 | cmdragon's Blog

往期文章归档：

• Nuxt.js 应用中的 schema：written 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 schema：beforeWrite 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 schema：resolved 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 vite：extendConfig 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 vite：extend 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 schema：extend事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 listen 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 prepare：types 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 build：error 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 prerender：routes 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 nitro：build：public-assets 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 nitro：build：before 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 nitro：init 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 nitro：config 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 components：extend 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 components：dirs 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 imports：dirs 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 imports：context 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 imports：extend 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 imports：sources 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 server：devHandler 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 pages：extend 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 builder：watch 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 builder：generateApp 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 build：manifest 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 build：done 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 build：before 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 app：templatesGenerated 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 app：templates 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 app：resolve 事件钩子详解 | cmdragon's Blog
• Nuxt.js 应用中的 modules：done 事件钩子详解 | cmdragon's Blog

在当今编程界，ChatGPT 就像一颗耀眼却又颇具争议的新星，它对编程有着不可忽视的影响。但这影响就像一把双刃剑，使用不当，就可能让我们在编程之路上“受伤”。

一、过度依赖 ChatGPT 编程：黑暗深渊里的重重危机

1、个人编程能力：被“偷走”的成长

想象一下，那些初涉编程的新手们，就像刚学走路的孩子。如果他们一遇到编程作业，就不假思索地向 ChatGPT 寻求答案，那可就像是一直被搀扶着，自己的双腿从未真正用力。就拿写一个简单的猜数字小游戏来说，直接从 ChatGPT 拿到代码，表面上是完成了任务，但实际上呢？对于代码中随机数是如何生成的、循环是怎样巧妙设计的，他们完全是一头雾水。长此以往，当真正需要独立编程的时候，比如在考试或者参与实际项目时，他们就会像离开拐杖的人，茫然失措，因为他们的编程能力从未真正成长。

2、业务理解：与现实的“脱轨”

编程和业务本应是紧密交织的齿轮，共同推动项目前进。可过度依赖 ChatGPT，就会让这个齿轮系统错乱。以开发电商平台为例，电商的世界就像一个复杂的迷宫，满是各种促销规则这样的“机关”。如果仅仅依靠 ChatGPT 生成代码，对于满减、买一送一等促销逻辑，代码可能就像是没头的苍蝇，无法准确处理。这就会导致在实际运营中，促销活动变成一团乱麻，用户体验一落千丈，电商平台的发展也会因此陷入困境。

3、职业发展：被堵死的晋升之路

在职场这个残酷的战场上，过度依赖 ChatGPT 的程序员就像是穿着沉重枷锁的战士。比如说公司要对库存管理系统升级，程序员如果长期依赖 ChatGPT，那就麻烦了。因为每个公司的库存管理都有自己的独特之处，像是特殊的分类方式和盘点规则。而 ChatGPT 的方案就像是千篇一律的模板，无法契合公司的实际情况。这样一来，项目进度就会像蜗牛爬行一样缓慢，甚至可能出现数据安全问题。在公司眼中，这样的程序员就像失去光芒的星星，无法展现价值，升职加薪自然成了泡影，甚至可能面临被淘汰的命运。

4、安全隐患：悬在头顶的“达摩克利斯之剑”

在软件开发的王国里，安全就是守护宝藏的巨龙。然而，过度依赖 ChatGPT 可能会让这条巨龙打瞌睡。就拿在线支付软件来说，这可是涉及用户资金安全和隐私的“金库”。如果盲目使用 ChatGPT 生成的代码，就可能像在金库的大门上留下了无数漏洞。比如在用户登录环节，可能没有足够强大的防盗号魔法，数据传输过程中也可能缺失安全的加密护盾。一旦黑客这个“恶龙”发现这些破绽，用户的资金和隐私就会被洗劫一空，给用户和软件公司都带来毁灭性的打击。

5、团队协作：被打乱的和谐乐章

在团队这个大乐队中，每个成员都应该是演奏精彩旋律的乐手。但如果有成员过度依赖 ChatGPT 编程，就像是一个不懂乐谱却在乱弹琴的人。比如在游戏开发的大合奏中，负责角色技能系统的成员使用 ChatGPT 生成代码，在代码整合这个关键的“合奏”环节，他可能完全无法解释清楚技能系统和其他系统（像角色属性系统、战斗系统）之间的交互逻辑。这就会导致技能效果在游戏中“跑调”，像技能暴击效果无法正确触发、游戏卡顿等问题频发，严重破坏了项目的进度和质量这个“乐章”的和谐，团队的协作氛围也会像被暴风雨袭击过的湖面，不再平静。

二、ChatGPT 在编程中的微光：并非一无是处

1、代码模板：编程路上的“快捷小道”

在一些常见的编程任务中，ChatGPT 就像是一位贴心的导游，能迅速为程序员指出一条代码模板的“快捷小道”。比如说基本的文件读写操作，它能快速生成一个可用的代码框架，就像为程序员搭建了一个简易的脚手架。程序员可以在这个基础上轻松地进行修改和完善，大大节省了时间，提高了编程的效率。

2、编程思路：黑暗中的“启明星”

当程序员在复杂的算法问题或者新的功能需求的“迷雾森林”中迷失时，ChatGPT 就像一颗闪亮的启明星，为他们指引方向。比如在解决复杂的图算法问题时，它展示的某种解法可能就像是打开宝藏的钥匙，启发程序员找到更合适的解决方案，帮助程序员拓宽思维，让他们在编程的“迷宫”中更快地找到出口。

三、挣脱依赖之网，开启编程能力升级之旅

1、筑牢编程基础：编程大厦的坚固基石

深入数据结构与算法的“魔法世界”

通过参加专业课程或线上教程，像探险家深入神秘洞穴一样，全面掌握数据结构（从简单的数组、链表，到复杂的树、图等）和算法（从常见的排序算法、搜索算法到更高级的算法）的原理和应用。例如，亲自尝试在编程中实现红黑树的插入、删除操作，体验如同施展魔法般的感觉，以及熟练运用各种排序算法。这样，在编程时就能像魔法师挑选合适的魔法咒语一样，根据实际情况选择最优的算法，而不被 ChatGPT 生成的代码迷惑。

成为编程语言的“主宰者”

对于常用的编程语言（Python、Java、C++等这些编程世界的“王国”），要像国王了解自己的领土一样深入学习其语法、特性和标准库。以 Python 为例，要深入理解生成器、装饰器这些神奇的“魔法工具”是如何工作的，掌握多线程和多进程模块这些“强大兵力”的使用方法。只有这样，在面对 ChatGPT 生成的代码时，才能像睿智的国王辨别真伪一样，准确判断其质量，并进行针对性的修改。

2、洞察业务逻辑：连接编程与现实的“桥梁”

与业务部门的“亲密对话”

在项目开发的“征途”前，要和业务部门进行像老友般的深入沟通。比如在开发金融风险评估软件时，要与金融专家、业务人员这些“行业智者”促膝长谈，了解不同金融产品的风险评估指标、计算方法和特殊规则这些“行业密码”，确保编写的代码能够像精准的指南针一样，准确反映业务逻辑。

绘制业务蓝图：从抽象到具体的“魔法画笔”

根据业务需求，拿起绘制业务模型和流程图的“魔法画笔”。在开发金融交易系统时，精心绘制从用户下单、交易撮合、资金结算到风险控制的整个流程这幅“宏伟画卷”，清晰地展现每个环节的业务规则和数据流向，让编程过程像沿着地图航行一样，紧密围绕业务逻辑展开，避免被 ChatGPT 的通用代码引入歧途。

3、强化安全意识：守护编程王国的“钢铁长城”

学习安全编程规范：安全防线的“建造手册”

深入钻研行业内的安全编程规范，如 OWASP 的安全编码指南这一“安全宝典”。在开发 Web 应用时，依据这个“宝典”对输入验证、输出编码、密码存储等环节进行像打造坚固城堡一样的严格安全处理，防止因使用 ChatGPT 代码而让“敌人”（黑客）有机可乘。

安全审计与测试：安全漏洞的“照妖镜”

在编程过程中，要定期拿起专业的代码扫描工具（如 Checkmarx、Fortify 等这些“照妖镜”）对代码进行安全审计，检查是否存在像隐藏在暗处的小妖怪一样的安全隐患。同时，开展各种安全测试，如渗透测试、漏洞扫描测试等，像英勇的卫士一样及时发现并修复 ChatGPT 代码可能存在的安全问题。

4、优化团队协作与知识共享：团队力量的“核聚变”

建立代码审查与分享“圆桌会议”

在团队中建立定期的代码审查“圆桌会议”，对成员编写的代码（包括使用 ChatGPT 生成并修改后的代码）进行像鉴赏珍宝一样的审查。在这个过程中，大家分享编程思路、业务逻辑实现方法和优化建议这些“智慧宝藏”。例如在开发移动应用时，通过审查用户登录模块的代码，讨论如何更好地实现记住密码功能及其安全性，让团队成员之间像知识的“魔法师”一样相互学习，减少对 ChatGPT 的依赖。

创建内部代码库和知识库：团队智慧的“宝库”

建立团队内部的代码库这个“宝藏仓库”，收集和整理经过实践检验的优质代码。同时，打造知识库这个“智慧殿堂”，记录业务需求分析、常见问题解决方案、编程技巧等内容。这样，成员在编程时就可以像在宝库中挑选武器一样，优先从内部资源中获取帮助，降低对 ChatGPT 的使用频率。并且鼓励成员将使用 ChatGPT 的经验和教训分享到知识库中，提高团队对其使用的警惕性。

5、实践出真知：编程能力提升的“黄金之路”

从小项目开启编程“冒险之旅”

模仿经典：站在巨人肩膀上的“起步”

从网络这个“魔法森林”中寻找一些经典的小型编程项目，如简单的命令行计算器、待办事项列表应用等，开启模仿练习的“冒险之旅”。在模仿过程中，不仅要实现基本功能，还要像学习古老魔法的学徒一样，学习优秀的代码风格和规范。以命令行计算器为例，在完成基本的四则运算功能这个“小魔法”后，逐步添加更复杂的功能，如括号运算、幂运算等，像升级魔法技能一样加深对编程的理解。

自主拓展：突破边界的“成长”

在完成模仿后，对小项目进行功能拓展，这就像是打破魔法封印一样。对于待办事项列表应用，可以增加任务优先级设置、按日期排序任务等功能。这需要像魔法师重新设计魔法阵一样，对数据结构和算法进行重新设计和优化，从而锻炼解决问题的能力和编程思维。

投身开源项目：编程江湖的“历练”

寻找合适项目：踏入开源江湖的“第一步”

根据自己的兴趣和技术水平，在开源平台（如 GitHub 这个“编程江湖”）上寻找合适的开源项目。例如，如果对 Web 开发感兴趣且有一定基础，可以选择一个小型的前端框架项目这个“门派”。在参与项目前，先像探秘神秘门派一样，仔细阅读项目的文档和代码结构，了解其实现原理和功能特点。

积极贡献与交流：江湖高手的“成长之路”

从简单的任务入手，如文档更新、代码格式化这些“基础招式”，熟悉开源项目的协作流程和代码规范。随着对项目的熟悉，像勇敢的江湖侠客一样尝试解决一些实际的代码问题，如修复 Bug 或添加新功能。在这个过程中，与其他开发者在项目的 issue 区这个“江湖茶馆”交流经验，学习他们的思路和方法，拓宽编程视野。

解决生活难题：编程魔法的“日常应用”

自动化日常：让生活充满“魔法”

将编程应用于日常生活中的问题解决，实现任务自动化，这就像是把魔法融入生活。例如，如果经常需要处理大量文件，可以编写 Python 脚本这个“魔法咒语”实现文件的批量重命名或格式转换。在这个过程中，学习如何使用编程语言操作文件系统，以及如何运用相关库（如
os
模块、
re
模块等）这些“魔法工具”实现复杂的功能。

开发实用工具：创造属于自己的“魔法神器”

根据自己的兴趣爱好或工作需求，开发一些实用的小工具，这就像是打造专属的魔法神器。比如，对于数据分析爱好者，可以开发一个简单的数据可视化工具。从使用 Python 的
matplotlib
或
seaborn
库绘制简单的柱状图、折线图这些“初级魔法绘图”开始，逐渐掌握如何将数据映射到图形元素上，设置坐标轴标签、标题等“高级魔法技巧”。随着经验的积累，尝试制作更复杂的可视化作品，如交互式的桑基图或地理信息图，以此提升编程能力。

四、与 ChatGPT 共舞，主宰编程之路

总之，ChatGPT 是编程世界里一个强大的“魔法助手”，但我们不能被它的“魔法”迷惑，陷入过度依赖的陷阱。我们要巧妙地利用它，同时通过各种途径提升自己的编程能力，深入理解业务逻辑，筑牢安全防线，优化团队协作，积极实践。只有这样，我们才能在编程这个充满魅力的“魔法世界”里不断成长，成为能够独立解决问题的编程高手，真正主宰自己的编程之路，而不是在依赖中迷失方向，成为被“魔法”控制的傀儡。

本文介绍基于
VBA
语言，对大量含有图片、文本框与表格的
Word
文档加以批量自动合并，并在每一次合并时
添加分页符
的方法。

在我们之前的文章中，介绍过基于
Python
语言的
python-docx
（
docx
）模块与
docxcompose
模块，对大量
Word
文档加以合并的方法；但是，基于这种方法，我们无法对
具有非明确大小的文本框
的
Word
加以合并，因为
python-docx
无法处理含有这种元素的
Word
文件。最近，一位老哥提出了合并
含有文本框
的
Word
的需求，所以就尝试用
VBA
来实现这一操作，这里就介绍一下具体的方法。

其中，
VBA
是Visual Basic for Applications的缩写，其是基于
Visual Basic
语言的一种扩展，主要应用于微软
Office
套件中各种应用程序，例如
Word
、
Excel
与
PowerPoint
等；其允许用户创建自定义的宏和应用程序来自动执行各种任务，从而提高工作效率。目前，
VBA
主要就是应用于需要批量操作
Office
文件的各类场景中。

本文的需求如下。现在有一个文件夹，其中包含大量文档文件，如下图所示；其中，每一个文档中，都包含图片、表格、文本框等
较为复杂的元素
。

我们现在希望，可以批量将文件夹中大量文档文件加以合并；并且在合并时，每次都需要在新的
1
页中合并下一个文件（也就是，不同文件的内容不要出现在
1
页中）。

明确了需求，即可开始代码撰写。本文所需代码如下。

Sub merge_word()
    Dim time_start As Single: time_start = Timer
    Dim word_result As Document
    Dim word_temp As Document
    Dim file_dialog As FileDialog
    Dim str As String
    Dim file
    Dim num As Long
    
    Set word_result = ActiveDocument
    Set file_dialog = Application.FileDialog(msoFileDialogFilePicker)
    
    With file_dialog
        .AllowMultiSelect = True
        .Title = "请选择【一个或多个】需要与当前文档合并的文件"
        With .Filters
            .Clear
            .Add "Word文件", "*.doc*;*.dot*;*.wps"
            .Add "所有文件", "*.*"
        End With
        If .Show Then
            Application.ScreenUpdating = False
            num = .SelectedItems.count
            For Each file In .SelectedItems
                Set word_temp = Documents.Open(file)
                word_temp.Range.Copy
                
                word_result.Range(word_result.Range.End - 1, word_result.Range.End).Select
                
                DoEvents
                Selection.Paste
                Selection.InsertBreak
                
                word_temp.Close wdDoNotSaveChanges
            Next
            
            Application.ScreenUpdating = True
        End If
    End With
    
    Set word_result = Nothing
    Set word_temp = Nothing
    Set file_dialog = Nothing
    
    str = Format(Timer - time_start, "均已成功合并；共用时0秒！")
    str = Format(num, "您选择合并0个文件，") & str
    MsgBox str, vbInformation, "文件合并结果"
End Sub

上述代码中，我们首先进行
变量声明
。
time_start
是一个
Single
类型的变量，用以记录代码开始执行的时间；
Timer
函数返回一个单精度浮点数，表示从计算机启动到现在经过的秒数。
word_result
是一个
Document
类型的变量，用以存储当前打开的
Word
文档。
word_temp
是另一个
Document
类型的变量，用以临时存储要合并的其他
Word
文档。
file_dialog
是一个
FileDialog
类型的变量，用以存储文件选择对话框对象。
str
是一个字符串类型的变量，用以存储最终要显示在消息框中的合并结果信息。
file
用以在循环中存储用户选择的每个文件路径。
num
是一个长整型变量，用以存储用户选择的文件数量。

随后，我们
获取当前文档
。将当前正在编辑的
Word
文档赋值给
word_result
变量，这个文档就是要合并其他文档内容的结果文档。

接下来，我们
打开文件选择对话框
。创建一个文件选择对话框对象，并逐一设置对话框的属性；其中，允许用户选择多个文件，自定义对话框标题，并设置文件类型过滤器，其中第一个表示只显示
Word
文档文件，第二个则表示显示所有类型的文件。

紧接着，通过
If .Show Then
语句，判断用户在对话框中是否选择了文件。如果是的话，执行合并操作。其中，首先获取用户选择的文件数量；随后，循环遍历每个选择的文件——打开每个选择的文件作为
临时文档
，将
临时文档
的全部内容复制到剪贴板；将光标定位到
目标文档
（也就是结果文件）的最后一个字符处，并将剪贴板中的内容粘贴到
目标文档
的末尾，同时在粘贴的内容后插入一个分页符；最后，关闭
临时文档
而不保存更改。接下来，进行下一次遍历。其中需要注意，这里如果我们不添加
DoEvents
这句代码，会导致其下方的
Selection.Paste
这句代码报错（虽然会报错，但其实选择调试后继续按下
F5
，程序也还是可以运行）。

最后，即可清理变量引用，并计算合并操作的耗时，将结果信息显示在消息框中。

代码的执行方法如下。首先，在任意路径创建一个空白的
Word
文档，作为我们的结果文件。随后，在这个文档中，同时按下
Alt
键与
F11
键，进入
VBA
宏界面，如下图所示。

随后，在左上角的
Normal
处右键，选择“
插入
”→“
模块
”，如下图所示。

随后，在弹出的窗口中，复制前述代码，如下图所示。

接下来，按下
F5
键，即可开始运行代码。其中，首先弹出一个选择文件的窗口，我们选择待合并的文件即可；如下图所示。

随后，点击“
确定
”，即可开始合并文件。稍等片刻，合并完成，并将弹出如下所示界面。

此时，回到我们打开的
Word
文件中，即可看到文件已经被合并在内了。

其中，上图中紫色框所示区域，就是我这里待合并文件的开头部分（紫色框内红色的两段线仅仅是为了遮挡文件中的部分信息，没有别的含义，大家理解即可）——可以看到，每一次新的文件合并时，都是在新的一页操作的，符合我们的需求。

至此，大功告成。

一、背景
数据的跨时钟域处理是FPGA开发过程中的常见问题，存在两种情况

1. 1. 慢时钟向快时钟同步：只需在快时钟域打两拍即可。其RTL如下：
      
   
   

   打拍同步的原理：大家在初学FPGA时，经常听过FPGA中对信号打拍可以有效得避免亚稳态，而且一般要打两拍，其数学本质是如果打一拍发生错误得概率是1/1000，那么打两拍发生错误得概率就是1/1000000，这从统计意义上已经无限接近0。
   从电路本身的角度上讲，如果一个信号的更新频率与当前时钟域内的信号更新频率不同步,那么其和当前时钟域内的信号做任何运算,都有可能导致结果出现毛刺或者不满足下级寄存器的建立或保持时间。因此,为了确保新引人的这个非本时钟域的信号不会对本时钟域造成毁灭性打击,必须对其进行同步化处理,而方法就是使用当前时钟地域的时钟对其进行采样。而进行两次打拍是让异步信号打两拍可以让异步过来的电平信号达到一个比较“健壮”的电平区间，二避免了由于建立时间、多级扇出导致的逻辑电平不稳定的情况。以下摘自《FPGA之道》：

“为什么要采样两次呢?
采样一次,已经完成了非本时钟域信号的同步操作,那么为什么还要采用两级采样法呢?虽然从逻辑上来看,两级采样法就跟移位寄存器一样,并不能改变信号的逻辑值,而且还会增加信号传递进来的延迟,但是这绝对不是画蛇添足,而是非常必要的,原因如下:请大家思考一下,进行第一级采样的那个寄存器,其建立和保持时间是不否能够得到满足?显然在有些情况下,其建立和保持时间是无法得到满足的,因为它和当前时钟域时钟信号的变化并不同步,因此总会碰到问题。例如,当asynsignal从0变化到1时,如果在过这前后时间内,clk共经历了3个上升沿,那么unsafesignal的输出可能是001,也可能是011,其中,第二次采样由于建立或者保持时间不满足,所以无法确定其是0还是1,不过值得欧慰的是,无论是001,还是011,都至少正确捕捉到了原始信号的变化。也许你会觉得,异步逻辑本身就不可能在时间上被精确地捕捉到,既然能够正确捕捉到信号的变化,那不就够了么?没错,从逻辑上来说是够了,但是从驱动能力上来说,也许不够。大家都知道,FPGA内部的工作电压一般为1.5V,也就是说,理想情况下,逻辑1对应电压1.5V,逻辑0对应电压0V。但是现实是残酷的,逻辑1不可能精确地是1.5V,逻辑0也不可能是精确地0V,事实上,也许业界公认0.5V以上就可以判定为逻辑1,反之则可以被判定为逻辑0,这也是为什么数字信信号比模拟信号更能抗干扰的原因。所以,如果现在问你,FPGA内部有两个触发器的输出都是逻辑1,那么它俩的物理电压相等吗?答案显然是不一定。为什么触发器能够给出正确地输出结果的前提是输入信号要满足其建立、保持时间要求?其实原因很简单,就是要给数字电路以充足的时间来进行充电或者放电操作,从而让其输出的逻辑1更接近于1.5V,逻辑0更接近于0V;反之,如果一个逻辑电平1、0对应的物理电平更接近于1.5V或者0V,那么它就更容易在规定时间内对其后级触发器进行充分的充电或放电控制,从而使其后级触发器的输出也更加"强壮"。那么现在,我们在回过头来审视unsafesignal的物理电压,由于输出unsafesignalf的触发器,很可能出现建立或保持时间要求不满足的情况,因此,在这种情况下,它的充、放电操作都很不充分,输出的逻辑1或者逻辑0的物理电压都不会太好。例如,如果unsafesignalj为逻辑1,那么其物理电压很可能为0.6V,如果当前时钟域中有很多地方都用到了unsafesignal,那么0.6V电压的扇出能力显然会比较差,因此等传递到后续各个用到unsafe signal的地方,物理电压可能就变为0.4V、0.5V、0.55V等等,那么这时 unsafe signal就会被不同的触发器认成不同的逻辑电平,于是错误便诞生了。为了避免这种情况的发生,我们对unsafesignal再次进行采样。由于unsafesignal和safesignal是同步的,因此对于输出safesignal的触发器来说,建立时间已经远远超出了其建立时间要求,因此,即使0.6V的电压对其充电比较慢,但由于充电时间足够,充电电流也有保障,所以也能让safesignal达到一个比较健壮的物理电压,例如1.4V。接下来,我们再将safesignal连接到各个需要使用它的地方,其扇出能力就不会再有任何问题了。”

1. 2.快时钟域向慢时钟域同步
   第一种简单的方式是在快慢时钟域间添加一个FIFO，这样就可以避免时钟不同步的问题。
   第二种方式是hand shanking机制，简单来说就是一种握手机制，其时序图可以用下图表示：
   
   在数据有效后，主机发起同步请求req,直至检测到从机的ACK信号后，req拉低，标志一次同步结束。而req信号在从机进行采样同步，并经过两拍后，从机对主机的DATA信号进行采样同步，完成从快时钟域到慢时钟域的数据同步。
   代码如下：

  `// ************************ ***************************************

// Copyright (C) xx Coporation 
// File name: hand_shanking.v  
// Author: Dongyang  
// Date: 2024-11/16 
// Version: 1.0  
// Abstract: CDC multi bit sync,use hand shanking to sync data
//***************************************************************** `
`timescale 1 ns/1 ns
module  hand_shanking_module# (
    parameter integer DATA_WIDTH = 8
    )
(
    input                            i_clk_f          ,     //
    input                            i_sys_rst_n      ,     //外部异步复位信号
    input       [DATA_WIDTH-1 : 0]   i_src_data       ,     //外部输入信号,
    input                            i_src_data_valid ,     //数据有效标志


    input                            i_clk_s          ,
    output                           o_des_ack        ,     //应答完成信号，取上升沿后可作为i_clk_s 的o_des_data 的valid 信号
    output  reg [DATA_WIDTH-1 : 0]   o_des_data            //在i_clk_s 时钟域同步后的信号
);

//******************** siganl define  ***********************
    reg                         r_src_req             ;
    reg                         r_src_ack_sync1       ;
    reg                         r_src_ack_sync2       ;
    
    reg                         r_des_req_sync1       ;
    reg                         r_des_req_sync2       ;
    
    reg                         r_des_ack             ; 

//************** combination  logic *************************
assign        o_des_ack = r_des_ack;
// step 1 , generate r_src_req 
always @(posedge i_clk_f or negedge i_sys_rst_n) begin
    if (~i_sys_rst_n) begin
        r_src_req <= 1'b0;
    end
    else begin
        if (i_src_data_valid) begin                  //once datavalid , generate r_src_req
            r_src_req <= 1'b1;
        end
        else if (r_src_ack_sync2) begin             // when i_clk_s domain ack successfully,r_src_req reset
            r_src_req <= 1'b0;
        end
    end
end

//step 2 and 3, under i_clk_s domain, sync r_src_req from i_clk_f domain,generate ack ok siganl
always @(posedge i_clk_s or negedge i_sys_rst_n) begin
    if (~i_sys_rst_n) begin
        r_des_req_sync1 <= 1'b0;
        r_des_req_sync2 <= 1'b0;
        r_des_ack       <= 1'b0;
    end
    else begin
        r_des_req_sync1 <= r_src_req ;
        r_des_req_sync2 <= r_des_req_sync1;
        r_des_ack       <= r_des_req_sync2;
    end
end
//step 3, once r_des_req_sync2 set, sync o_des_data
always @(posedge i_clk_s or negedge i_sys_rst_n) begin
     if (~i_sys_rst_n) begin
        o_des_data <= 'b0;
     end
     else begin
        if(r_des_req_sync2) begin
            o_des_data <= i_src_data;
        end
     end
end


//step 4 ,sync r_des_ack to i_clk_f domain
always@(posedge i_clk_f or negedge i_sys_rst_n) begin
    if(~i_sys_rst_n) begin
        r_src_ack_sync1 <= 1'b0;
        r_src_ack_sync2 <= 1'b0;
    end
    else begin
        r_src_ack_sync1 <= r_des_ack;
        r_src_ack_sync2 <= r_src_ack_sync1;

    end
end

endmodule

TestBench:

`timescale 1 ns/1 ns
module tb_hand_shanking();

parameter integer DATA_WIDTH =  8;

reg                         clk_f      = 'b0;
reg                         clk_s      = 'b0;
reg                         sys_rst_n  = 'b0;
reg   [DATA_WIDTH- 1 : 0 ]  src_data   = 'b0;
reg                         data_valid = 'b0;

always # 10   clk_f = ~ clk_f;
always # 30   clk_s = ~ clk_s;

initial begin
    clk_f      = 'b0;
    clk_s      = 'b0;
    sys_rst_n  = 'b0;
    src_data   = 'b0;
    data_valid = 'b0;
    #50
    sys_rst_n <= 1'b1;
    #100
    src_data <= 8'h5A;
    data_valid <= 1'b1;
    #20
    data_valid <= 1'b0;
    #500
    src_data <= 8'h6A;
    data_valid <= 1'b1;
    #20
    data_valid <= 1'b0;

end

hand_shanking_module  
#(
        .DATA_WIDTH(DATA_WIDTH)
)
 U_hand_shanking_module_0 
(
    .i_clk_f             (clk_f),
    .i_sys_rst_n         (sys_rst_n),
    .i_src_data          (src_data),
    .i_src_data_valid    (data_valid),
    .i_clk_s             (clk_s),
    .o_des_ack           (),
    .o_des_data          ()
 
);

endmodule

仿真波形：
https://img2024.cnblogs.com/blog/3539410/202411/3539410-20241116161229825-134001601.png