目录

Vue3 集成

最后更新: 2026-01-27 11:02:47

Vue3 集成

Unicode Framework 提供了完整的 Vue3 集成支持，包括服务端渲染（SSR）和单页应用（SPA）支持。

快速开始

1. 安装依赖

<h1 id="安装-nodejs-依赖用于-ssr">安装 Node.js 依赖（用于 SSR）</h1>
cd resources/vue3-ssr
npm install vue@3 @vue/server-renderer

2. 启动 SSR 服务（如果使用 SSR）

<h1 id="开发环境">开发环境</h1>
node resources/vue3-ssr/ssr-server.js

<h1 id="生产环境使用-pm2">生产环境（使用 PM2）</h1>
pm2 start resources/vue3-ssr/ssr-server.js --name vue-ssr

3. 配置视图引擎

在 config/view.php 中配置：

return [
    'default_engine' => 'vue',  // 设置 Vue3 为默认引擎

'engines' => [
        'vue' => [
            'vue3_ssr' => [
                'enabled' => true,
                'mode' => 'http',  // 使用 HTTP 模式（推荐）
                'ssr_server_url' => 'http://127.0.0.1:3000',
            ],
        ],
    ],
];

4. 创建第一个 Vue 模板

创建 app/{app_name}/view/index/index.vue：

<template>
  <div class="welcome">
    <h1>{{ title }}</h1>
    <p>{{ message }}</p>
  </div>
</template>

<script>
export default {
  props: {
    title: String,
    message: String,
  },
};
</script>


<style>
.welcome {
  padding: 20px;
}
</style>

5. 在控制器中使用

use function view;

$html = view('index/index', [
    'title' => '欢迎',
    'message' => 'Hello Vue3!',
], 'vue');

Vue3 基础

使用 Vue3 模板引擎

框架支持两种使用方式：

方式一：使用 view() 辅助函数 
use function view;

// 使用 Vue3 引擎渲染模板
$html = view('user/profile', ['user' => $user], 'vue');

方式二：直接使用引擎 
use Unicode\Framework\View\VueViewEngine;

$engine = new VueViewEngine($config);
$html = $engine->render('user/profile', ['user' => $user]);

渲染完整页面

使用 renderFullPage() 方法可以自动生成完整的 HTML 文档结构：

use function viewFullPage;

$html = viewFullPage('user/profile', ['user' => $user], 'vue', [
    'title' => '用户资料',
    'cdn_resources' => [
        'css' => ['/vendor/element-plus@latest/index.css'],
        'js' => ['/vendor/vue@3/vue.global.prod.js'],
    ],
]);

Vue3 SPA

渲染 SPA 入口

使用 vue_spa() 辅助函数渲染 Vue3 单页应用入口：

use function vue_spa;
use Unicode\Framework\Http\Response;

return Response::html(vue_spa(
    initialData: ['user' => $user],
    appId: 'app',
    entryFile: 'js/main.js',
    options: [
        'title' => '我的应用',
        'meta' => [
            'description' => '应用描述',
        ],
    ]
));

基本用法

namespace App\Index\Controller;

use Unicode\Framework\Http\Response;
use function vue_spa;


class IndexController
{
    public function index(): Response
    {
        $html = vue_spa(
            initialData: [
                'user' => $user,
                'config' => [
                    'apiUrl' => '/api',
                ],
            ],
            appId: 'app',
            entryFile: 'js/main.js',
            options: [
                'title' => '我的应用',
                'meta' => [
                    'description' => '应用描述',
                ],
            ]
        );


return Response::html($html);
    }
}

传递初始数据

$html = vue_spa([
    'user' => [
        'id' => 1,
        'name' => 'John Doe',
        'email' => 'john@example.com',
    ],
    'settings' => [
        'theme' => 'dark',
        'language' => 'zh-CN',
    ],
], 'app', 'js/main.js');

在 Vue 应用中使用

// public/js/main.js
import { createApp } from "vue";

// 获取初始数据
const initialDataElement = document.getElementById("__INITIAL_DATA__");
const __INITIAL_DATA__ = initialDataElement
  ? JSON.parse(initialDataElement.textContent)
  : {};
initialDataElement?.remove();


// 创建 Vue 应用
const app = createApp({
  data() {
    return __INITIAL_DATA__;
  },
  mounted() {
    console.log(this.user); // 访问初始数据
  },
});


app.mount("#app");

Vue3 SSR

概述

Vue3 SSR（服务端渲染）支持两种模式：

  • HTTP 模式（推荐）：通过 HTTP 请求调用常驻的 Node.js SSR 服务，性能更好
  • 进程模式（已废弃）：每次渲染启动新的 Node.js 进程，性能较差

    • 启用 SSR

    在 config/view.php 中配置：

    return [
    'engines' => [
        'vue' => [
            'vue3_ssr' => [
                'enabled' => true,
                'mode' => 'http',  // 使用 HTTP 模式（推荐）
                'ssr_server_url' => 'http://127.0.0.1:3000',
                'http_timeout' => 10,
                'enable_hydration' => true,
                'vue_cdn' => 'https://unpkg.com/vue@3/dist/vue.esm-browser.js',
            ],
        ],
    ],
];

    安装依赖

    <h1 id="进入-ssr-资源目录">进入 SSR 资源目录</h1>
cd resources/vue3-ssr

    <h1 id="安装依赖">安装依赖</h1>
npm install vue@3 @vue/server-renderer

    启动 SSR 服务

    开发环境： 
    node resources/vue3-ssr/ssr-server.js
    生产环境（使用 PM2）： 
    pm2 start resources/vue3-ssr/ssr-server.js --name vue-ssr
pm2 save
    使用环境变量： 
    PORT=3000 HOST=127.0.0.1 node resources/vue3-ssr/ssr-server.js

    使用 SSR

    use function view;

    // 使用 Vue3 SSR 渲染
$html = view('user/profile', ['user' => $user], 'vue');

    SSR 工作原理

  • PHP 调用 Node.js SSR 服务（HTTP 模式）或启动 Node.js 进程（进程模式）
  • Node.js 使用 Vue3 SSR 渲染组件
  • 返回渲染后的 HTML
  • 客户端激活（Hydration，可选）

    • 客户端激活（Hydration）

    启用客户端激活后，Vue3 会在客户端接管服务端渲染的 HTML：

    // 配置中启用
'enable_hydration' => true,

    // 使用 renderWithHydration 方法
use Unicode\Framework\View\VueViewEngine;

    $engine = new VueViewEngine($config);
$html = $engine->renderWithHydration('user/profile', ['user' => $user], 'app');


    // 客户端代码
import { createApp } from "vue";

    const app = createApp({
  // 组件定义
});
    

    // 激活服务端渲染的 HTML
app.mount("#app");

    HTTP 模式 vs 进程模式

    | 特性 | HTTP 模式 | 进程模式 | | -------- | ------------- | ----------- | | 性能 | 5-20ms | 100-300ms | | 吞吐量 | 100-500 req/s | 10-30 req/s | | 内存占用 | 中 | 高 | | 推荐场景 | 生产环境 | 不推荐 |

    > 注意：进程模式已废弃，建议使用 HTTP 模式。详细说明请参考 Vue3 SSR HTTP 模式指南。

    .vue 单文件组件

    支持的功能

    框架完全支持 .vue 单文件组件格式：

  • ✅ 自动解析