我们经常听到“巨石应用”这个词。那种动辄几万行代码、启动慢如蜗牛、改一处动全身的项目，简直是开发者的噩梦。这时候，微前端架构就像是一把利剑，帮我们劈开了混沌。而在众多的微前端解决方案中，字节跳动开源的 Garfish 凭借其出色的性Neng和兼容性，赢得了不少开发者的青睐。

今天咱们不聊枯燥的理论，直接来点实战的。我想带大家从零开始，利用目前Zui火热的包管理工具 pnpm，配合 Vite，搭建一套基于 Garfish 的微前端 Monorepo 仓库。相信我，当你kan到多个子应用完美运行在一个主基座中时那种成就感是无与伦比的。

一、 准备工作：工欲善其事，必先利其器

在开始敲代码之前，我们得先把环境整明白。既然要玩微前端，Node.js 的版本不Neng太老，建议保持在 v16+，这样Neng避免hen多奇奇怪怪的坑。至于包管理器，我强烈推荐使用 pnpm。

为什么是 pnpm 而不是 npm 或 yarn？简单来说它极快、极省空间。对于 Monorepo这种结构，pnpm 的 workspace 功Neng简直是天作之合。它Neng通过硬链接的方式共享依赖，避免每个子应用dou重复安装一遍 node_modules，这点在微前端项目中尤为重要，毕竟我们的子应用数量可Neng会随着业务增长而不断增加。

Ru果你还没安装 pnpm，赶紧执行下面这行命令：

npm install -g pnpm

装好之后我们Ke以新建一个项目文件夹，比如叫 garfish-pnpm-monorepo，然后进去开始我们的表演。

二、 Monorepo 基础架构搭建

我们要搭建的是一个标准的 Monorepo 结构。所有的子应用dou会放在 packages 目录下。为了告诉 pnpm 哪些目录属于我们的工作空间，我们需要在根目录下创建一个核心配置文件：pnpm-workspace.yaml。

这个文件的内容其实非常直观，就像是在告诉 pnpm：“嘿，去 packages 文件夹里找所有的应用，它们dou是一家人。”

packages:
  - 'packages/*'

当然为了geng规范一点，我们也Ke以显式地指定每一个子应用，比如：

packages:
  - 'packages/main-app'
  - 'packages/vue-app'
  - 'packages/react-app'

配置好这个文件后pnpm 就Neng聪明地帮我们管理依赖关系了。接下来我们需要在根目录初始化一下 package.json，方便后续管理全局的脚本命令。

npm init -y

三、 打造主应用

主应用是微前端架构中的“大脑”，它负责调度子应用、管理路由以及提供公共的容器。这里我们选择 Vue3 + Vite 来构建主应用，毕竟 Vite 的开发体验实在是太丝滑了而且 Garfish 对 Vite 的生态支持也相当不错。

1. 初始化主应用项目

我们在 packages 目录下创建一个 main-app 文件夹，并利用 Vite 的脚手架快速生成项目模板。

mkdir -p packages/main-app
cd packages/main-app
pnpm create vite@latest . --template vue

生成完项目后记得回到根目录，把主应用的依赖装上。这里有个小技巧，使用 -F 参数，Ke以指定只安装某个子包的依赖，而不会影响到其他包。

cd ../../
pnpm install -F main-app

2. 引入 Garfish 核心库

主应用需要安装 Garfish 的核心包以及路由模块。为了方便所有子应用复用这些依赖，我们推荐在根目录安装，并加上 -Dw 参数，表示安装到根目录的开发依赖中。

pnpm add garfish @garfish/router -Dw

3. 配置 Vite 与跨域

在微前端开发中，主应用通常需要从不同的端口加载子应用资源，这就涉及到了跨域问题。我们需要在 packages/main-app/vite.config.js 中Zuo一些手脚。

把主应用的端口固定下来比如设为 8080，防止每次启动dou随机变动导致子应用找不到家。必须开启 cors: true，否则浏览器会无情地拦截子应用的请求。

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
  plugins: ,
  server: {
    port: 8080, // 固定端口，避免到处找地址
    cors: true, // 开启跨域，这是子应用加载的前提
  },
})

4. 编写 Garfish 启动逻辑

这是Zui关键的一步。我们需要在主应用中初始化 Garfish，并告诉它有哪些子应用Ke以加载。为了保持代码整洁，建议在 src 目录下单独建一个 micro-app.js 文件来管理这些配置。

在这个文件里我们需要调用 Garfish.run。这里有几个核心配置项需要注意：domGetter 指定了子应用挂载的容器 ID；apps 数组则列出了所有子应用的信息，包括名字、入口地址、激活路由规则等。

import Garfish from 'garfish';
import { createRouter } from '@garfish/router';
export function initGarfish {
  // 初始化路由
  const garfishRouter = createRouter;
  // 启动 Garfish
  Garfish.run({
    // 子应用挂载的容器，必须和 App.vue 中的 ID 对应
    domGetter: '#micro-app-container',
    // 开启沙箱，隔离样式和 JS，防止子应用“打架”
    sandbox: {
      open: true,
      strictIsolation: true,
    },
    // 注册子应用列表
    apps: ,
    // 路由配置
    router: garfishRouter,
    // 生命周期钩子，方便调试
    lifecycle: {
      beforeMount:  => console.log,
      mounted:  => console.log,
    },
  });
}

写好配置后别忘了在 main.js 中引入并执行这个初始化函数。通常我们会在主应用挂载完成后启动微前端。

import { createApp } from 'vue'
import App from './App.vue'
import { initGarfish } from './micro-app.js'
const app = createApp
app.mount
// 启动微前端
initGarfish

5. 修改主应用页面

Zui后我们需要在 App.vue 中留出位置给子应用。通常我们会放一个导航栏，方便用户切换，然后放一个空的 div 作为子应用的挂载点。

四、 开发子应用

主应用搭好了现在我们来填充内容。先创建一个 Vue3 的子应用。过程和创建主应用类似，只不过这次我们要把它放在 packages/vue-app 下。

mkdir -p packages/vue-app
cd packages/vue-app
pnpm create vite@latest . --template vue
cd ../../
pnpm install -F vue-app

1. 修改 Vite 配置

子应用的配置比主应用要稍微讲究一点。base 路径必须和主应用配置中的 basename 保持一致，否则资源加载会出错。端口要固定，并且同样需要开启 cors。为了保险起见，显式指定 origin 也是个好习惯。

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
  plugins: ,
  base: '/vue-app/', // 重要！与主应用配置一致
  server: {
    port: 8081,
    cors: true,
    origin: 'http://localhost:8081',
  },
  build: {
    outDir: '../../dist/vue-app', // 统一输出到根目录的 dist 下
  },
})

2. 适配生命周期

这是子应用接入 Garfish 的核心。Garfish 要求子应用导出特定的生命周期函数，比如 render和 destroy。我们需要改造 main.js，让它既Neng独立运行，也Neng被主应用接管。

这里有个小窍门：通过判断 window.__GARFISH__ 是否存挂载容器由主应用传入；否则，挂载到默认的 #app。

import { createApp } from 'vue'
import App from './App.vue'
import './style.css'
let app = null
function render {
  const { container } = props
  // Ru果有 container，就挂载到主应用传来的节点；否则挂载到自己的 #app
  app = createApp
  app.mount : '#app')
}
// 独立运行时
if  {
  render
}
// 导出生命周期供 Garfish 调用
export const provider = {
  render,
  destroy {
    // 卸载应用，清理内存
    if  {
      app.unmount
      app = null
    }
    // 清理 DOM
    const dom = container ? container.querySelector : document.querySelector
    if  dom.innerHTML = ''
  },
}

3. 修改根组件

记得给 App.vue 加上 id="app"，因为上面的代码里我们用到了这个选择器。

五、 开发子应用

为了展示 Garfish 的强大兼容性，我们再接入一个 React 子应用。步骤大同小异，只是在生命周期的处理上，React 的 API 稍有不同。

mkdir -p packages/react-app
cd packages/react-app
pnpm create vite@latest . --template react
cd ../../
pnpm install -F react-app

React 的 vite.config.js 配置和 Vue 几乎一样，只需要把端口改成 8082，base 改成 /react-app/ 即可。重点kan main.jsx

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'
let root = null
function render {
  const { container } = props
  const dom = container ? container.querySelector : document.getElementById
  root = ReactDOM.createRoot
  root.render(
    
      
    
  )
}
if  {
  render
}
export const provider = {
  render,
  destroy {
    const dom = container ? container.querySelector : document.getElementById
    if  {
      root.unmount
      root = null
    }
    if  dom.innerHTML = ''
  },
}

六、 统一管理与运行

现在主应用和两个子应用dou准备好了。难道我们要开三个终端窗口分别启动吗？那也太麻烦了。这时候，concurrently 这个工具就派上用场了。它允许我们并行执行多个命令。

先安装一下：

pnpm add concurrently -Dw

然后在根目录的 package.json 中配置我们的脚本。我们Ke以分别定义启动各个应用的命令，Zui后再来一个“一键启动”的大杀器。

{
  "scripts": {
    "dev:main": "pnpm -F main-app dev",
    "dev:vue": "pnpm -F vue-app dev",
    "dev:react": "pnpm -F react-app dev",
    "dev": "concurrently \"pnpm dev:main\" \"pnpm dev:vue\" \"pnpm dev:react\"",
    "build:main": "pnpm -F main-app build",
    "build:vue": "pnpm -F vue-app build",
    "build:react": "pnpm -F react-app build",
    "build": "pnpm run build:main && pnpm run build:vue && pnpm run build:react"
  }
}

配置好后只需要在根目录敲下 pnpm dev你就会kan到三个应用同时启动了是不是hen酷？

七、 构建与部署

开发环境跑通了生产环境怎么办？其实hen简单。执行 pnpm build 后所有应用的产物dou会输出到对应的 dist 目录。

部署时你需要把主应用和子应用的静态资源dou扔到服务器上。Zui重要的是记得修改主应用 Garfish 配置中的 entry 地址，把 localhost:xxxx 换成线上真实的 HTTP 地址。只要路径配置对了一切就Neng像在本地一样顺滑运行。

到这里一套完整的基于 pnpm 和 Garfish 的微前端架构就搭建完成了。虽然过程中涉及到了不少配置细节，比如跨域、生命周期适配、路径规范等，但一旦这套流程跑通，后续新增子应用简直就是复制粘贴的事儿。

微前端不仅仅是技术的堆砌，geng是一种架构思维的转变。它让我们敢于将庞大的系统拆解，让不同的团队Ke以独立开发、独立部署，Zui后又Neng无缝地组合在一起。希望这篇实战文章Neng帮你迈出 Garfish 微前端的第一步，祝你在前端架构的道路上越走越远！

---