企业官网建设流程全解析

• 后端
• 微服务
• 云原生

Midway Hooks 提供了一套名为@midwayjs/hooks-kit的全栈套件，让前端开发者可以在同一个项目里同时编写浏览器端与 Node.js 服务端代码，并通过一套统一的命令行（hooks dev/hooks build/hooks start）完成开发、构建与启动。本文以官方文档 hooks/fullstack.md 为主线，完整讲解全栈套件的模板生态、CLI 用法与构建参数，并结合仓库中的配置文档、部署文档和真实示例工程，给出可直接落地的前后端一体化开发方案。

全栈套件是什么

在 Midway Hooks 的一体化方案中，"全栈套件"（Full Stack Kit）指通过@midwayjs/hooks-kit快速开发全栈应用的能力。它解决了传统前后端分离项目中最耗时的一环——前后端之间的通信胶水层。

正如 intro.md 所介绍的，一体化方案建立在标准 Midway 项目之上，扩展出一层前端适配层，项目中同时存在前端代码和 Node 代码。后端接口函数可以直接被前端导入并调用，无需手写 Ajax 调用层，即"零 Api"；配合@midwayjs/hooks的校验器，还能低成本实现从前端到后端的静态类型安全与运行时安全。而@midwayjs/hooks-kit全栈套件正是这一体验的载体：hooks dev启动全栈应用，hooks build打包全栈应用，hooks start在服务端一键启动，解决使用全栈应用时的后顾之忧。

需要注意的是，当前仓库的官方文档也在 intro.md 中提示：一体化方案将逐步停止维护，已有项目可以继续使用，新建项目请谨慎选择。因此在评估是否选用全栈套件时，请结合这一维护状态做出判断。

开箱即用的模板

官方文档说明，目前提供了以下可以直接使用的全栈模板：

• react：React + Vite 的全栈应用模板
• vue：Vue 的全栈应用模板
• prisma：集成 Prisma ORM 的全栈应用模板

这些模板可以在对应的 examples 目录中找到。本仓库中也有与之对应的、可直接运行的示例工程，例如：

• samples/react-functional-api：一个可运行的 React (Vite) 项目，演示src/server/api下的defineApi定义、前端直接导入服务端 API 定义、createClient客户端调用等能力；
• samples/vue-functional-api：Vue 版本的全栈示例，目录结构（src/server、src/web、vite.config.ts等）与 React 示例一一对应。

以 React 示例为例，其目录组织方式如下（摘自 samples/react-functional-api/README.md）：

samples/react-functional-api/ package.json tsconfig.json vite.config.ts index.html src/ main.tsx server/ configuration.ts api/ user.api.ts web/ app.tsx api/ client.ts

后端 API 集中在src/server/api，前端页面逻辑在src/web，两者在同一个工程内协作。在仓库根目录执行pnpm -C samples/react-functional-api install安装依赖，再执行pnpm -C samples/react-functional-api dev，即可启动一个内嵌 Midway HTTP 运行时的 Vite 开发服务器，/api/*请求会交给src/server/api中真实的 Midway 路由处理。

命令行界面（hooks CLI）

在使用了@midwayjs/hooks-kit的项目中，可以通过 npm scripts 使用hooks可执行文件，也可以通过npx hooks直接运行。通过脚手架创建的 Midway 全栈项目默认包含以下 npm scripts：

{ "scripts": { "dev": "hooks dev", // 启动开发服务器 "start": "hooks start", // 启动生产服务器，使用前请确保已运行 `npm run build` "build": "hooks build" // 为生产环境构建产物 } }

三个命令各司其职：

hooks start与hooks dev的关键区别在于运行环境：dev面向开发迭代，通常包含热重载与更宽松的日志；start直接运行构建后的产物，因此文档特别强调"使用前请确保已运行npm run build"。这要求生产发布流程遵循"先 build、后 start"的顺序。

命令行参数与 hooks build --help

使用命令行时，可以通过命令行参数向hooks传入选项，具体选项可以通过--help查看。官方文档以hooks build --help为例：

hooks build --help

输出：

Usage: $ hooks build [root] Options: --outDir <dir> [string] output directory (default: dist) --clean [boolean] clean output directory before build (default: false) -h, --help Display this message

对以上参数逐一说明：

• [root]：可选的构建根目录位置参数。缺省时使用当前目录，即从调用命令所在的项目根目录开始构建。
• --outDir <dir>：输出目录，类型为 string，默认值为dist。构建产物会写入该目录。这与项目配置中的build.outDir配置项对应（默认同为./dist），命令行参数优先于配置文件。
• --clean：布尔开关，默认值为false。置为true时，在构建前清空输出目录，避免旧的构建产物残留造成污染。
• -h, --help：显示帮助信息。

同理，hooks dev与hooks start也支持通过--help查看各自可用的选项。在编写 CI/CD 脚本时，建议先运行一次--help，以确认当前安装版本实际支持的参数集合，避免因版本差异导致参数失效。

通过 midway.config.ts 配置全栈项目

全栈套件的项目配置集中在项目根目录的midway.config.ts中。根据 config.md 的说明，核心配置项如下：

其中vite配置项是前端工程能力的入口。例如，为 React 全栈应用注册@vitejs/plugin-react插件：

import react from '@vitejs/plugin-react'; import { defineConfig } from '@midwayjs/hooks-kit'; export default defineConfig({ vite: { plugins: [react()], }, });

如果项目是纯接口项目（无前端），因为需要在生成环境读取配置，应使用 JavaScript 配置文件，文件名为midway.config.js，这是文档中特别强调的一点。

构建产物结构：前端与后端的落点

理解全栈套件的构建产物结构，是正确部署的前提。根据 deploy.md，全栈套件项目默认的构建目录为dist，其中：

• dist/_client：前端静态资源目录（HTML、JS、CSS、图片等）；
• dist/_serve：后端服务入口；
• 其余目录下的*.js：编译后的后端业务代码与配置。

一份典型的构建产物布局如下：

dist ├── _client │ ├── assets │ │ ├── index.85bb4f15.js │ │ ├── index.b779b14d.css │ │ └── vendor.346bc0da.js │ ├── index.html │ ├── logo.png │ └── manifest.json ├── _serve │ └── index.js ├── book.js ├── configuration.js ├── date.js ├── midway.config.js └── star.js

这就对应了hooks build --outDir的默认值dist：构建命令将前后端统一产出到该目录，部署时只需上传整个dist目录即可。

三种部署模式与 CDN 集成

基于上述产物结构，deploy.md 给出了三种由易到难的一体化部署模式：

1. 前后端部署在同一服务器：全栈套件默认模式，将dist产物整体上传服务器后启动即可。最简单，但静态资源不在 CDN，跨地域访问速度不稳定。

2. 静态资源部署至 CDN，后端托管 HTML 并提供接口：需要自行将_client目录下的静态资源上传 CDN，同时保留_client/index.html供后端托管。可通过vite.base指定静态资源的公共域名：

   import react from '@vitejs/plugin-react'; import { defineConfig } from '@midwayjs/hooks-kit'; export default defineConfig({ vite: { plugins: [react()], base: 'https://cdn.example.com', }, });

   设置后，页面访问时静态资源会指向 CDN 地址。

3. 静态资源在 CDN，HTML 由单独服务托管，后端仅提供接口：需要禁用全栈套件默认的 index.html 托管能力，使构建时不生成 HTML 托管函数，仅提供 API 服务：

   import { defineConfig } from '@midwayjs/hooks-kit'; export default defineConfig({ static: false, });

   随后在 CI/CD 中对三类产物分别处理：index.html部署至 Nginx / CDN 等托管服务，静态资源部署至 OSS 等 CDN 加速服务，API 服务部署至服务器，并可配置https://example.com/api等反向代理路径。

在本仓库中实践全栈开发

本仓库的 samples/react-functional-api 是理解全栈套件运行时协作机制的绝佳入口。它的 vite.config.ts 展示了全栈开发的两类关键插件：

import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import { apiPlugin } from '@midwayjs/web-bridge/vite'; import { devPlugin } from '@midwayjs/mock/vite'; export default defineConfig({ build: { outDir: 'dist/web', }, plugins: [ devPlugin({ appDir, baseDir, basePath }), react(), apiPlugin({ root, apiDir, target: 'both' }), ], });

• devPlugin：在开发环境下把 Midway HTTP 运行时嵌入 Vite，/api/*请求直接进入服务端路由处理；
• apiPlugin：将 API 定义接入 Vite 构建链路，target: 'both'意味着 CSR 与 SSR 构建可以共用同一套 API 导入方式。

该示例的运行说明中还有几个与部署决策直接相关的提示：客户端调用默认以/api为basePath；后端是真实的 Midway Koa 应用；如果后端包含 Redis / MQ / WebSocket 等长连接，建议将后端独立运行，再由 Vite 代理/api。这些细节与上文"三种部署模式"的判断标准相互印证，可作为搭建生产环境时的参考。

小结

@midwayjs/hooks-kit全栈套件通过统一的hooksCLI 把"开发（dev）— 构建（build）— 启动（start）"串成一条完整链路：hooks build支持--outDir与--clean参数控制产物输出，midway.config.ts中的source、build.outDir、vite、static等配置决定了前后端的组织方式与部署形态，dist/_client与dist/_serve的分工则明确了 CDN 与服务器的职责边界。结合本仓库的 react/vue 示例工程，开发者可以快速搭建并验证自己的全栈应用。

继续深入可参考：hooks/intro.md（一体化方案总览与模板创建）、hooks/config.md（全部配置项说明）、hooks/deploy.md（三种部署模式与 CI/CD 工作流）。

• 后端
• 微服务
• 云原生