❌

普通视图

发现新文章，点击刷新页面。
昨天 — 2025年12月25日首页

🎉TinyVue v3.27.0 正式发布：增加 Space 新组件，ColorPicker 组件支持线性渐变

✇掘金 前端
作者 前端开源星球
2025年12月25日 17:22
你好，我是 Kagol，个人公众号：前端开源星球。 我们非常高兴地宣布 TinyVue v3.27.0 正式发布🎉。该版本聚焦于增强可定制性与可访问性，新增若干实用组件能力，并修复了大量用户反馈的关键

🔥🔥高效易用的 Vue3 公告滚动组件：打造丝滑的内容滚动体验(附源码)

✇掘金 前端
作者 同学80796
2025年12月25日 16:38
在各类后台管理系统、营销页面或信息展示场景中，公告滚动是高频且基础的交互需求 —— 既要实现内容自动向上滚动的展示效果，也要兼顾用户手动操作的灵活性。基于 Vue3 Setup 语法糖封装的这款公告滚

2025年OpenTiny年度人气贡献者评选正式开始

✇掘金 前端
作者 OpenTiny社区
2025年12月25日 14:56

前言

携手共创，致敬不凡！

2025年，OpenTiny持续在前端开源领域扎根，每一位开发者都是推动项目共同前行的宝贵力量。从bug修复，到技术探讨；从参与开源活动，到输出技术文章；从使用项目，到参与共建，每一步跨越，都凝聚了开发者的智慧与汗水。 致敬所有在OpenTiny社区里默默付出、积极贡献、引领创新的杰出个人，我们正式启动“OpenTiny年度贡献者评选”活动！快为你喜爱的人气贡献者投票吧~

人气贡献者评选

名单公布：

新1.PNG

年度贡献者投票评选时间：

2025年12月25日-2025年12月31日

投票规则：

每人每天可回答3次，每次最多可投2票，最终投票结果选取前5名

投票入口：

wj.qq.com/s2/25333949…

去水印.png

关于OpenTiny

欢迎加入 OpenTiny 开源社区。添加微信小助手：opentiny-official 一起参与交流前端技术～
OpenTiny 官网：opentiny.design
OpenTiny 代码仓库：github.com/opentiny
TinyVue 源码：github.com/opentiny/ti…
TinyEngine 源码：github.com/opentiny/ti…
欢迎进入代码仓库 Star🌟TinyEngine、TinyVue、TinyNG、TinyCLI~ 如果你也想要共建，可以进入代码仓库，找到 good first issue标签，一起参与开源贡献~

Vue3 调用 Coze 工作流：从上传宠物照到生成冰球明星的完整技术解析

✇掘金 前端
作者 AAA阿giao
2025年12月25日 11:00

 引言

“你家的猫，也能打冰球？”
不是玩笑——这是一次前端与 AI 工作流的完美邂逅。

在当今 AI 应用爆发的时代，开发者不再满足于调用单一模型 API，而是通过 工作流（Workflow） 编排多个能力节点，实现复杂业务逻辑。而前端作为用户交互的第一线，如何优雅地集成这些 AI 能力，成为现代 Web 开发的重要课题。

本文将带你深入剖析一个真实项目：使用 Vue3 前端调用 Coze 平台的工作流 API，上传一张宠物照片，生成穿着定制队服、手持冰球杆的运动员形象图。我们将逐行解读 App.vue 源码，解释每一个 API 调用、每一段逻辑设计，并结合完整的 Coze 工作流图解，还原整个数据流转过程。文章内容严格引用原始代码（一字不变），确保技术细节 100% 准确。

一、项目背景与目标

AI 应用之冰球前端应用 vue3：冰球协会，上传宠物照片，生成运动员的形象照片。

这个应用的核心功能非常明确：

  • 用户上传一张宠物（或人物）照片；
  • 选择冰球队服编号、颜色、场上位置、持杆手、艺术风格等参数；
  • 点击“生成”，系统调用 AI 工作流；
  • 返回一张合成后的“冰球运动员”图像。

而这一切的实现，完全依赖于 Coze 平台提供的工作流 API。前端负责收集输入、上传文件、发起请求、展示结果——典型的“轻前端 + 重 AI 后端”架构。

二、App.vue 整体结构概览

App.vue 是一个标准的 Vue3 单文件组件（SFC），采用 <script setup> 语法糖，结合 Composition API 实现响应式逻辑。整体分为三部分：

  1. <template> ：用户界面（UI）
  2. <script setup> ：业务逻辑（JS）
  3. <style scoped> ：样式（CSS）

我们先从模板入手，理解用户看到什么、能做什么。

三、模板（Template）详解：用户交互层

3.1 文件上传与预览

<div class="file-input">
  <input 
    type="file" 
    ref="uploadImage" 
    accept="image/*" 
    @change="updateImageData" required />
</div>
<img :src="imgPreview" alt="" v-if="imgPreview"/>
  • <input type="file">：原生文件选择器，限制只接受图片（accept="image/*"）。
  • ref="uploadImage"：通过 ref 获取该 DOM 元素，便于 JS 中读取文件。
  • @change="updateImageData"：当用户选择文件后，立即触发 updateImageData 方法，生成本地预览。
  • imgPreview 是一个响应式变量，用于显示 Data URL 格式的预览图，无需上传即可看到效果。

✅ 用户体验亮点：即使图片很大、上传很慢，用户也能立刻确认自己选对了图。

3.2 表单参数设置

接下来是两组设置项，全部使用 v-model 双向绑定：

第一组：队服信息

<div class="settings">
  <div class="selection">
    <label>队服编号:</label>
    <input type="number" v-model="uniform_number"/>
  </div>
  <div class="selection">
    <label>队服颜色:</label>
    <select v-model="uniform_color">
      <option value="红">红</option>
      <option value="蓝">蓝</option>
      <option value="绿">绿</option>
      <option value="白">白</option>
      <option value="黑">黑</option>
    </select>
  </div>
</div>
  • uniform_number：默认值为 10（见 script 部分），支持任意数字。
  • uniform_color：限定五种颜色，值为中文字符串（如 "红"）。

第二组：角色与风格

<div class="settings">
  <div class="selection">
    <label>位置：</label>
    <select v-model="position">
      <option value="0">守门员</option>
      <option value="1">前锋</option>
      <option value="2">后卫</option>
    </select>
  </div>
  <div class="selection">
    <label>持杆：</label>
    <select v-model="shooting_hand">
      <option value="0">左手</option>
      <option value="1">右手</option>
    </select>
  </div>
  <div class="selection">
    <label>风格：</label>
    <select v-model="style">
      <option value="写实">写实</option>
      <option value="乐高">乐高</option>
      <option value="国漫">国漫</option>
      <option value="日漫">日漫</option>
      <option value="油画">油画</option>
      <option value="涂鸦">涂鸦</option>
      <option value="素描">素描</option>
    </select>
  </div>
</div>
  • position 和 shooting_hand 的值虽然是数字字符串（"0"/"1"/"2"），但前端显示为中文，兼顾可读性与后端兼容性。
  • style 提供 7 种艺术风格，极大增强趣味性和分享欲。

3.3 生成按钮与输出区域

<div class="generate">
  <button @click="generate">生成</button>
</div>

点击后触发 generate() 函数，启动整个 AI 生成流程。

输出区域：

<div class="output">
  <div class="generated">
    <img :src="imgUrl" alt="" v-if="imgUrl"/>
    <div v-if="status">{{ status }}</div>
  </div>
</div>
  • imgUrl：存储 Coze 返回的生成图 URL。
  • status：动态显示当前状态（如“上传中…”、“生成失败”等），避免用户焦虑。

💡 设计哲学：状态反馈是良好 UX 的核心。没有反馈的“生成”按钮，等于黑盒。

四、脚本逻辑（Script Setup）深度解析

现在进入最核心的部分——JavaScript 逻辑。

4.1 环境配置与常量定义

import { ref, onMounted } from 'vue'

const patToken = import.meta.env.VITE_PAT_TOKEN;
const uploadUrl = 'https://api.coze.cn/v1/files/upload';
const workflowUrl = 'https://api.coze.cn/v1/workflow/run';
const workflow_id = '7584046136391630898';

  • import.meta.env.VITE_PAT_TOKEN：Vite 提供的环境变量注入机制。.env 文件中应包含：

    VITE_PAT_TOKEN=cztei_lvNwngHgch9rxNlx4KiXuky3UjfW9iqCZRe17KDXjh22RLL8sPLsb8Vl10R3IHJsW

  • uploadUrl：Coze 官方文件上传接口（文档）。

  • workflowUrl：触发工作流的入口（文档）。

  • workflow_id：在 Coze 控制台创建的工作流唯一 ID，内部已配置好图像生成逻辑（如调用文生图模型、叠加队服等）。

⚠️ 安全警告：将 PAT Token 放在前端仅适用于演示或内部工具。生产环境应通过后端代理 API，避免 Token 泄露。

4.2 响应式状态声明

const uniform_number = ref(10);
const uniform_color = ref('红');
const position = ref(0);
const shooting_hand = ref(0);
const style = ref('写实');

const status = ref('');
const imageUrl = ref('');
  • 所有表单字段均为 ref 响应式对象，确保视图自动更新。
  • status 初始为空，后续将显示：“图片上传中...” → “图片上传成功, 正在生成...” → 成功清空 或 错误信息。
  • imageUrl 初始为空，生成成功后赋值为图片 URL。

4.3 核心函数 1：图片预览（updateImageData）

const uploadImage = ref(null);
const imgPreview = ref('');

const updateImageData = () => {
  const input = uploadImage.value;
  if (!input.files || input.files.length === 0) {
    return;
  }
  const file = input.files[0];
  const reader = new FileReader();
  reader.readAsDataURL(file);
  reader.onload = (e) => {
    imgPreview.value = e.target.result;
  };
}
  • uploadImage 是对 <input> 元素的引用。
  • 使用 FileReader 的 readAsDataURL 方法，将文件转为 Base64 编码的 Data URL。
  • onload 回调中，将结果赋给 imgPreview，触发 <img> 标签渲染。

✅ 优势：纯前端实现，零网络请求，秒级响应。

4.4 核心函数 2：文件上传（uploadFile）

const uploadFile = async () => {
  const formData = new FormData();
  const input = uploadImage.value;
  if (!input.files || input.files.length <= 0) return;
  formData.append('file', input.files[0]);

  const res = await fetch(uploadUrl, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${patToken}`
    },
    body: formData
  });

  const ret = await res.json();
  console.log(ret);
  if (ret.code !== 0) {
    status.value = ret.msg;
    return;
  }
  return ret.data.id;
}

逐行解析：

  1. 构造 FormData：

    • new FormData() 是浏览器原生 API，用于构建 multipart/form-data 请求体，专为文件上传设计。
    • formData.append('file', file)：Coze 要求字段名为 file。

  2. 发送 POST 请求：

    • URL：https://api.coze.cn/v1/files/upload

    • Headers：

      • Authorization: Bearer <token>：Coze 使用 Bearer Token 认证。

    • Body：formData 自动设置正确 Content-Type（含 boundary）。

  3. 处理响应：

    • 成功时返回：

      { "code": 0, "msg": "success", "data": { "id": "file_xxx", ... } }

    • 失败时 code !== 0，msg 包含错误原因（如 Token 无效、文件过大等）。

    • 函数返回 file_id（如 "file_abc123"），供下一步使用。

关键点：Coze 的文件上传是独立步骤，必须先上传获取 file_id，才能在工作流中引用。

五、核心函数 3：调用工作流（generate）

这是整个应用的“大脑”。我们结合 Coze 工作流图，深入分析其逻辑与数据流。

const generate = async () => {
  status.value = "图片上传中...";
  const file_id = await uploadFile();
  if (!file_id) return;

  status.value = "图片上传成功, 正在生成...";

  const parameters = {
    picture: JSON.stringify({ file_id }),
    style: style.value,
    uniform_color: uniform_color.value,
    uniform_number: uniform_number.value,
    position: position.value,
    shooting_hand: shooting_hand.value,
  };

  try {
    const res = await fetch(workflowUrl, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${patToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ workflow_id, parameters })
    });

    const ret = await res.json();
    console.log("Workflow API response:", ret);
    if (ret.code !== 0) {
      status.value = ret.msg;
      return;
    }

    // 检查返回数据结构
    console.log("Return data:", ret.data);
    console.log("Return data type:", typeof ret.data);

    // 尝试解析数据
    let data;
    if (typeof ret.data === 'string') {
      try {
        data = JSON.parse(ret.data);
        console.log("Parsed data:", data);
      } catch (e) {
        console.error("JSON parse error:", e);
        status.value = "数据解析错误";
        return;
      }
    } else {
      data = ret.data;
    }

    // 检查data.data是否存在
    if (data && data.data) {
      console.log("Generated image URL:", data.data);
      status.value = '';
      imageUrl.value = data.data;
    } else {
      console.error("Invalid data structure, missing 'data' field:", data);
      status.value = "返回数据结构错误";
    }
  } catch (error) {
    console.error("Generate error:", error);
    status.value = "生成失败，请检查网络连接";
  }
}

逻辑拆解（结合 Coze 工作流图）

Coze 工作流结构（图解说明）

图注：

  1. 开始节点：接收 picture, style, uniform_number, position, shooting_hand, uniform_color 等参数。
  2. 分支一：imgUnderstand_1（图像理解）→ 分析上传图片内容（如动物种类、姿态）。
  3. 分支二：代码 节点 → 根据 position, shooting_hand, style 等生成描述文本（如“一只狗，右手持杆，身穿红色10号队服，站在冰球场上”）。
  4. 大模型节点：将图像理解结果与描述文本合并，生成最终提示词（prompt）。
  5. 图像生成节点：调用文生图模型（如豆包·1.5·Pro·32k），生成新图像。
  6. 结束节点：输出生成图的 URL。

前端代码的对应关系

前端参数 Coze 输入字段 用途
picture picture 图片文件 ID，传入 imgUnderstand_1 和 图像生成 节点
style style 传递给 代码 节点，决定艺术风格
uniform_number uniform_number 用于生成描述
position position 决定角色动作（如守门员蹲姿）
shooting_hand shooting_hand 决定持杆手
uniform_color uniform_color 用于生成队服颜色

💡 关键点：前端只需提供原始参数，Coze 工作流内部完成所有逻辑编排。

数据流全过程

  1. 前端上传文件 → 得到 file_id

  2. 前端组装参数 → 发送至 /workflow/run

  3. Coze 工作流执行：

    • imgUnderstand_1：分析图片内容 → 输出 text, url, content
    • 代码 节点：根据参数生成描述 → 如 "一只猫，身穿蓝色10号队服，右手持杆，站在冰球场上，风格为乐高"
    • 大模型 节点：合并图像理解结果与描述 → 生成最终 prompt
    • 图像生成 节点：调用模型生成图像 → 返回 data 字段（URL）

  4. 前端接收响应：

    • 若 ret.data 是字符串 → 尝试 JSON.parse
    • 若是对象 → 直接取 data.data
    • 最终赋值给 imageUrl

✅ 为什么需要双重解析？
因为 Coze 的“图像生成”节点可能直接返回 URL 字符串，也可能返回 { data: "url" } 结构。前端必须兼容两种情况。

六、样式（Style）简析

<style scoped>
.container {
  display: flex;
  flex-direction: row;
  align-items: start;
  justify-content: start;
  height: 100vh;
  font-size: .85rem;
}
.generated {
  width: 400px;
  height: 400px;
  border: solid 1px black;
  display: flex;
  justify-content: center;
  align-items: center;
}
.output img {
  width: 100%;
}
</style>
  • 使用 Flex 布局，左右分栏（输入区固定宽度，输出区自适应）。
  • .generated 容器固定 400x400，图片居中显示，无论原始比例如何都不变形。
  • scoped 确保样式仅作用于当前组件，避免污染全局。

七、项目运行

在项目终端运行命令 ：npm run dev

运行界面如下：

选择图片及风格等内容后，点击开始生成，运行结果如图：

总结：为什么这个项目值得学习？

  1. 真实场景：不是 Hello World，而是完整产品逻辑。

  2. 技术全面：

    • Vue3 Composition API
    • 文件上传与预览
    • Fetch API 与错误处理
    • 环境变量管理
    • 响应式状态驱动 UI

  3. AI 集成范式：展示了如何将复杂 AI 能力封装为简单 API，前端只需“填参数 + 拿结果”。

  4. 用户体验优先：状态提示、本地预览、错误反馈一应俱全。

安全与部署建议：

  • 后端代理所有 Coze API 调用：

    • 前端 → 自己的后端（/api/generate）
    • 后端 → Coze（携带安全存储的 Token）

  • 限制工作流权限：Coze 的 PAT Token 应仅授予必要权限。

  • 添加速率限制：防止滥用。

最终，技术的意义在于创造快乐。
当你上传一张狗子的照片，看到它穿上红色10号球衣、右手持杆、以“乐高”风格站在冰场上——
你会笑，会分享，会说：“AI 真酷！”

而这，正是我们写代码的初心。

完整项目源码：lesson_zp/ai/app/iceball: AI + 全栈学习仓库 - Gitee.com

vue 甘特图 vxe-gantt 任务里程碑和依赖线的使用

✇掘金 前端
作者 用户84179481456
2025年12月25日 09:45

vue 甘特图 vxe-gantt 任务里程碑和依赖线的使用

gantt.vxeui.com/

extend_gantt_chart_gantt_milestone_links

通过设置 task-bar-milestone-config 和 type=moveable 启用里程碑类型，当设置为里程碑类型时，只需要设置 start 开始日期就可以，无需设置 end 结束日期，设置 links 定义连接线,from 对应源任务的行主键,tom 对应目标任务的行主键

<template>
  <div>
    <vxe-gantt v-bind="ganttOptions"></vxe-gantt>
  </div>
</template>

<script setup>
import { reactive } from 'vue'
import { VxeGanttDependencyType, VxeGanttTaskType } from 'vxe-gantt'

const ganttOptions = reactive({
  border: true,
  height: 500,
  rowConfig: {
    keyField: 'id' // 行主键
  },
  taskBarConfig: {
    showProgress: true, // 是否显示进度条
    showContent: true, // 是否在任务条显示内容
    moveable: true, // 是否允许拖拽任务移动日期
    resizable: true, // 是否允许拖拽任务调整日期
    barStyle: {
      round: true, // 圆角
      bgColor: '#fca60b', // 任务条的背景颜色
      completedBgColor: '#65c16f' // 已完成部分任务条的背景颜色
    }
  },
  taskViewConfig: {
    tableStyle: {
      width: 280 // 表格宽度
    },
    gridding: {
      leftSpacing: 1, // 左侧间距多少列
      rightSpacing: 4 // 右侧间距多少列
    }
  },
  taskBarMilestoneConfig: {
    // 自定义里程碑图标
    icon ({ row }) {
      if (row.id === 10001) {
        return 'vxe-icon-warning-triangle-fill'
      }
      if (row.id === 10007) {
        return 'vxe-icon-square-fill'
      }
      if (row.id === 10009) {
        return 'vxe-icon-warning-circle-fill'
      }
      return 'vxe-icon-radio-unchecked-fill'
    },
    // 自定义里程碑图标样式
    iconStyle ({ row }) {
      if (row.id === 10001) {
        return {
          color: '#65c16f'
        }
      }
      if (row.id === 10007) {
        return {
          color: '#dc3cc7'
        }
      }
    }
  },
  taskLinkConfig: {
    lineType: 'flowDashed'
  },
  links: [
    { from: 10001, to: 10002, type: VxeGanttDependencyType.StartToFinish },
    { from: 10003, to: 10004, type: VxeGanttDependencyType.StartToStart },
    { from: 10007, to: 10008, type: VxeGanttDependencyType.StartToStart },
    { from: 10008, to: 10009, type: VxeGanttDependencyType.FinishToFinish },
    { from: 10009, to: 10010, type: VxeGanttDependencyType.FinishToStart }
  ],
  columns: [
    { type: 'seq', width: 70 },
    { field: 'title', title: '任务名称' }
  ],
  data: [
    { id: 10001, title: '项目启动会议', start: '2024-03-01', end: '', progress: 0, type: VxeGanttTaskType.Milestone },
    { id: 10002, title: '项目启动与计划', start: '2024-03-03', end: '2024-03-08', progress: 80, type: '' },
    { id: 10003, title: '需求评审完成', start: '2024-03-03', end: '', progress: 0, type: VxeGanttTaskType.Milestone },
    { id: 10004, title: '技术及方案设计', start: '2024-03-05', end: '2024-03-11', progress: 80, type: '' },
    { id: 10005, title: '功能开发', start: '2024-03-08', end: '2024-03-15', progress: 70, type: '' },
    { id: 10007, title: '测试环境发布', start: '2024-03-11', end: '', progress: 0, type: VxeGanttTaskType.Milestone },
    { id: 10008, title: '系统测试', start: '2024-03-14', end: '2024-03-19', progress: 80, type: '' },
    { id: 10009, title: '测试完成', start: '2024-03-19', end: '', progress: 0, type: VxeGanttTaskType.Milestone },
    { id: 10010, title: '正式发布上线', start: '2024-03-20', end: '', progress: 0, type: VxeGanttTaskType.Milestone }
  ]
})
</script>

gitee.com/x-extends/v…

昨天以前首页

Vue3自定义渲染器：原理剖析与实践指南

✇掘金 前端
作者 小白菜的编程日记
2025年12月24日 17:42

Vue3的自定义渲染器是框架架构中的一项革命性特性，它打破了Vue只能用于DOM渲染的限制，让开发者能够将Vue组件渲染到任意目标平台。本文将深入探讨Vue3自定义渲染器的核心原理，并通过TresJS这个优秀的3D渲染库来展示其实际应用。

什么是自定义渲染器

在传统的Vue应用中，渲染器负责将Vue组件转换为DOM元素。而Vue3引入的自定义渲染器API允许我们创建专门的渲染器，将Vue组件转换为任意类型的目标对象。TresJS正是利用这一特性，将Vue组件转换为Three.js的3D对象，让开发者能够使用声明式的Vue语法来构建3D场景。

传统DOM渲染器 vs 自定义渲染器

传统DOM渲染器的操作流程非常直观：

// Vue DOM渲染器操作
const div = document.createElement('div')  // 创建元素
div.textContent = 'Hello World'           // 设置属性
document.body.appendChild(div)            // 挂载到父元素
div.style.color = 'red'                   // 更新属性
document.body.removeChild(div)            // 卸载元素

而TresJS的自定义渲染器执行类似的操作，但目标对象是Three.js对象：

// TresJS渲染器操作
const mesh = new THREE.Mesh()                    // 创建Three.js对象
mesh.material = new THREE.MeshBasicMaterial()    // 设置属性
scene.add(mesh)                                  // 添加到场景
mesh.position.set(1, 2, 3)                       // 更新属性
scene.remove(mesh)                               // 从场景移除

自定义渲染器API核心

TresJS的自定义渲染器（nodeOps）实现了一套操作接口，当Vue需要执行以下操作时会调用这些接口：

  • 创建新的Three.js对象
  • 将对象添加到场景或其他对象中
  • 更新对象属性
  • 从场景中移除对象

这种架构设计让Vue的组件系统与具体的渲染目标解耦，使得同一个组件模型可以驱动不同的渲染后端。

响应式系统在3D渲染中的挑战

Vue的响应式系统虽然强大，但在3D场景中需要谨慎使用。在60FPS的渲染循环中，不当的响应式使用会导致严重的性能问题。

性能挑战

Vue的响应式基于JavaScript Proxy，每次属性访问和修改都会被拦截。在3D渲染循环中，这意味着每秒60次触发响应式系统：

// ❌ 这种做法会导致性能问题
const position = reactive({ x: 0, y: 0, z: 0 })

const { onBeforeRender } = useLoop()
onBeforeRender(() => {
  // 每秒触发Vue响应式系统60次
  position.x = Math.sin(Date.now() * 0.001) * 3
  position.y = Math.cos(Date.now() * 0.001) * 2
})

性能对比数据令人警醒：普通对象的属性访问可达每秒5000万次，而响应式对象由于代理开销只能达到每秒200万次。

解决方案：模板引用的艺术

模板引用（Template Refs）提供了直接访问Three.js实例的能力，避免了响应式开销，是动画和频繁更新的最佳选择：

// ✅ 推荐做法：使用模板引用
const meshRef = shallowRef(null)

const { onBeforeRender } = useLoop()
onBeforeRender(({ elapsed }) => {
  if (meshRef.value) {
    // 直接属性修改，无响应式开销
    meshRef.value.rotation.x = elapsed * 0.5
    meshRef.value.rotation.y = elapsed * 0.3
    meshRef.value.position.y = Math.sin(elapsed) * 2
  }
})

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 0, 5]" />
    <TresAmbientLight />
    
    <!-- 模板引用连接到Three.js实例 -->
    <TresMesh ref="meshRef">
      <TresBoxGeometry />
      <TresMeshStandardMaterial color="#ff6b35" />
    </TresMesh>
  </TresCanvas>
</template>

浅层响应式：平衡的艺术

当需要部分响应式时，shallowRef和shallowReactive提供了完美的平衡：

// ✅ 只让顶层属性具有响应性
const meshProps = shallowReactive({
  color: '#ff6b35',
  wireframe: false,
  visible: true,
  position: { x: 0, y: 0, z: 0 }  // 这个对象不是深度响应式的
})

// UI控制修改外观
const toggleWireframe = () => {
  meshProps.wireframe = !meshProps.wireframe  // 响应式更新
}

const { onBeforeRender } = useLoop()
onBeforeRender(() => {
  if (meshRef.value) {
    // 直接位置修改，无响应式开销
    meshRef.value.position.y = Math.sin(Date.now() * 0.001) * 2
  }
})

最佳实践模式

1. 初始定位与动画分离

使用响应式属性进行初始定位，使用模板引用进行动画：

// ✅ 响应式初始状态
const initialPosition = ref([0, 0, 0])
const color = ref('#ff6b35')

// ✅ 模板引用用于动画
const meshRef = shallowRef(null)

const { onBeforeRender } = useLoop()
onBeforeRender(({ elapsed }) => {
  if (meshRef.value) {
    // 相对于初始位置进行动画
    meshRef.value.position.y = initialPosition.value[1] + Math.sin(elapsed) * 2
  }
})

2. 计算属性优化复杂计算

对于不应在每帧运行的昂贵计算，使用计算属性：

// ✅ 计算属性只在依赖改变时重新计算
const orbitPositions = computed(() => {
  const positions = []
  for (let i = 0; i < settings.objects; i++) {
    const angle = (i / settings.objects) * Math.PI * 2
    positions.push({
      x: Math.cos(angle) * settings.radius,
      z: Math.sin(angle) * settings.radius
    })
  }
  return positions
})

3. 基于生命周期的更新

使用Vue的生命周期钩子处理性能敏感的更新：

const animationState = {
  time: 0,
  amplitude: 2,
  frequency: 1
}

const { onBeforeRender } = useLoop()
onBeforeRender(({ delta }) => {
  if (!isAnimating.value || !meshRef.value) return
  
  // 更新非响应式状态
  animationState.time += delta
  
  // 应用到Three.js实例
  meshRef.value.position.y = Math.sin(animationState.time * animationState.frequency) * animationState.amplitude
})

常见陷阱与规避

陷阱1：在动画中使用响应式数据

// ❌ 避免：在渲染循环中使用响应式对象
const rotation = reactive({ x: 0, y: 0, z: 0 })

onBeforeRender(({ elapsed }) => {
  rotation.x = elapsed * 0.5  // 每帧触发Vue响应式系统
  rotation.y = elapsed * 0.3
})

解决方案：使用模板引用

// ✅ 推荐：直接实例操作
const meshRef = shallowRef(null)

onBeforeRender(({ elapsed }) => {
  if (meshRef.value) {
    meshRef.value.rotation.x = elapsed * 0.5
    meshRef.value.rotation.y = elapsed * 0.3
  }
})

陷阱2：深度响应式数组

// ❌ 避免：深度响应式数组更新
const particles = reactive(Array.from({ length: 100 }, (_, i) => ({
  position: { x: i, y: 0, z: 0 },
  velocity: { x: 0, y: 0, z: 0 }
})))

onBeforeRender(() => {
  particles.forEach((particle) => {
    // 100个响应式对象的开销极大
    particle.position.x += particle.velocity.x
  })
})

解决方案：非响应式数据+模板引用

// ✅ 推荐：普通对象+模板引用
const particleData = Array.from({ length: 100 }, (_, i) => ({
  position: { x: i, y: 0, z: 0 },
  velocity: { x: (Math.random() - 0.5) * 0.1, y: 0, z: 0 }
}))

const particleRefs = shallowRef([])

onBeforeRender(() => {
  particleData.forEach((particle, index) => {
    // 更新普通对象数据
    particle.position.x += particle.velocity.x
    
    // 应用到Three.js实例
    const mesh = particleRefs.value[index]
    if (mesh) {
      mesh.position.set(particle.position.x, particle.position.y, particle.position.z)
    }
  })
})

性能监控与优化

使用性能监控工具如@tresjs/leches来实时监控FPS：

import { TresLeches, useControls } from '@tresjs/leches'

// 启用FPS监控
useControls('fpsgraph')

核心要点总结

Vue3自定义渲染器为跨平台渲染开辟了全新的可能性，但在3D渲染这样的高性能场景中，需要明智地选择响应式策略：

  1. 模板引用优先：在渲染循环中使用模板引用直接操作Three.js实例，避免响应式开销
  2. 浅层响应式：当需要部分响应式时，使用shallowRef和shallowReactive获得平衡
  3. 关注点分离：保持UI状态的响应性和动画状态的非响应性，以获得最佳性能
  4. 持续监控：使用性能监控工具识别3D场景中的响应式瓶颈

通过理解并应用这些模式，开发者可以创建既具有Vue开发体验优势，又能在高性能3D环境中流畅运行的应用。Vue3自定义渲染器不仅是一个技术特性，更是连接声明式编程与多样化渲染目标的桥梁，为前端开发开启了全新的创作空间。

Vue.js 插槽机制深度解析：从基础使用到高级应用

✇掘金 前端
作者 进击的野人
2025年12月24日 16:37

引言：组件化开发中的灵活性与可复用性

在现代前端开发中，组件化思想已成为构建复杂应用的核心范式。Vue.js作为一款渐进式JavaScript框架，提供了强大而灵活的组件系统。然而，在组件通信和数据传递方面，单纯的props和事件机制有时难以满足复杂场景的需求。这时，Vue的插槽（Slot）机制便显得尤为重要。本文将通过分析提供的代码示例，深入探讨Vue插槽的工作原理、分类及应用场景。

一、插槽的基本概念与作用

1.1 什么是插槽

插槽是Vue组件化体系中的一项关键特性，它允许父组件向子组件指定位置插入任意的HTML结构。这种机制本质上是一种组件间通信的方式，但其通信方向与props相反——是从父组件到子组件的内容传递。

如readme.md中所定义的，插槽的核心作用是"挖坑"与"填坑"。子组件通过<slot>标签定义一个"坑位"，而父组件则负责用具体内容来"填充"这个坑位。这种设计模式极大地增强了组件的灵活性和可复用性。

1.2 为什么需要插槽

在传统的组件设计中，子组件的内容通常是固定的，或者只能通过props传递简单的数据。但在实际开发中，我们经常遇到这样的需求：组件的基本结构相同，但内部内容需要根据使用场景灵活变化。

例如，一个卡片组件（Card）可能有统一的标题样式、边框阴影等，但卡片的主体内容可能是文本、图片、表单或任何其他HTML结构。如果没有插槽机制，我们需要为每种内容类型创建不同的组件，或者通过复杂的条件渲染逻辑来处理，这都会导致代码冗余和维护困难。

二、默认插槽：最简单的插槽形式

2.1 默认插槽的基本用法

观察第一个App.vue文件中的代码：

vue

复制下载

<template>
  <div class="container">
    <MyCategory title="美食">
      <img src="./assets/logo.png" alt="">
    </MyCategory>
    <MyCategory title="游戏">
      <ul>
        <li v-for="(game,index) in games" :key="index">{{ game }}</li>
      </ul>
    </MyCategory>
  </div>
</template>

在第一个MyCategory.vue中，子组件的定义如下：

vue

复制下载

<template>
  <div class="category">
    <h3>{{ title}}</h3>
    <slot>我是默认插槽（挖个坑，等着组件的使用者进行填充）</slot>
  </div>
</template>

这里展示的是默认插槽的使用方式。当父组件在<MyCategory>标签内部放置内容时，这些内容会自动填充到子组件的<slot>位置。

2.2 默认内容与空插槽处理

值得注意的是，<slot>标签内部可以包含默认内容。当父组件没有提供插槽内容时，这些默认内容会被渲染。这为组件提供了良好的降级体验，确保组件在任何情况下都有合理的显示。

三、作用域插槽：数据与结构的解耦

3.1 作用域插槽的核心思想

作用域插槽是Vue插槽机制中最强大但也最复杂的概念。如其名所示，它解决了"作用域"问题——数据在子组件中，但如何展示这些数据却由父组件决定。

在第二个App.vue文件中，我们看到了作用域插槽的实际应用：

vue

复制下载

<template>
  <div class="container">
    <MyCategory title="游戏">
      <template v-slot="{games}">
        <ul>
          <li v-for="(game,index) in games" :key="index">{{ game }}</li>
        </ul>
      </template>
    </MyCategory>
    
    <MyCategory title="游戏">
      <template v-slot="{games}">
        <ol>
          <li v-for="(game,index) in games" :key="index">{{ game }}</li>
        </ol>
      </template>
    </MyCategory>
  </div>
</template>

对应的子组件MyCategory.vue（第二个版本）为：

vue

复制下载

<template>
  <div class="category">
    <h3>{{ title}}</h3>
    <slot :games="games">我是默认插槽</slot>
  </div>
</template>

<script>
export default {
  name:'MyCategory',
  props:['title'],
  data(){
    return{
      games: ['王者荣耀','和平精英','英雄联盟'],
    }
  }
}
</script>

3.2 作用域插槽的工作原理

作用域插槽的精妙之处在于它实现了数据与表现层的分离：

  1. 数据在子组件：游戏数据games是在MyCategory组件内部定义和维护的
  2. 结构在父组件决定：如何展示这些游戏数据（用<ul>还是<ol>，或者其他任何结构）由父组件决定
  3. 通信通过插槽prop：子组件通过<slot :games="games">将数据"传递"给插槽内容

这种模式特别适用于：

  • 可复用组件库的开发
  • 表格、列表等数据展示组件的定制化
  • 需要高度可配置的UI组件

3.3 作用域插槽的语法演变

在Vue 2.6.0+中，作用域插槽的语法有了统一的v-slot指令。上述代码中使用的就是新语法：

vue

复制下载

<template v-slot="{games}">
  <!-- 使用games数据 -->
</template>

这等价于旧的作用域插槽语法：

vue

复制下载

<template slot-scope="{games}">
  <!-- 使用games数据 -->
</template>

四、插槽的高级应用与最佳实践

4.1 具名插槽：多插槽场景的解决方案

虽然提供的代码示例中没有展示具名插槽，但readme.md中已经提到了它的基本用法。具名插槽允许一个组件有多个插槽点，每个插槽点有独立的名称。

具名插槽的典型应用场景包括：

  • 布局组件（头部、主体、底部）
  • 对话框组件（标题、内容、操作按钮区域）
  • 卡片组件（媒体区、标题区、内容区、操作区）

4.2 插槽的编译作用域

理解插槽的编译作用域至关重要。父级模板里的所有内容都是在父级作用域中编译的；子模板里的所有内容都是在子作用域中编译的。这意味着：

  1. 父组件无法直接访问子组件的数据
  2. 子组件无法直接访问父组件的数据
  3. 插槽内容虽然最终出现在子组件的位置，但它是在父组件的作用域中编译的

这也是作用域插槽存在的根本原因——为了让父组件能够访问子组件的数据。

4.3 动态插槽名与编程式插槽

Vue 2.6.0+还支持动态插槽名，这为动态组件和高度可配置的UI提供了可能：

vue

复制下载

<template v-slot:[dynamicSlotName]>
  <!-- 动态内容 -->
</template>

4.4 插槽的性能考量

虽然插槽提供了极大的灵活性，但过度使用或不当使用可能会影响性能：

  1. 作用域插槽的更新：作用域插槽在每次父组件更新时都会重新渲染，因为插槽内容被视为子组件的一部分
  2. 静态内容提升：对于静态的插槽内容，Vue会进行优化，避免不必要的重新渲染
  3. 合理使用v-once：对于永远不会改变的插槽内容，可以考虑使用v-once指令

五、实际项目中的插槽应用模式

5.1 布局组件中的插槽应用

在实际项目中，插槽最常见的应用之一是布局组件。例如，创建一个基础布局组件：

vue

复制下载

<!-- BaseLayout.vue -->
<template>
  <div class="base-layout">
    <header>
      <slot name="header"></slot>
    </header>
    <main>
      <slot></slot>
    </main>
    <footer>
      <slot name="footer"></slot>
    </footer>
  </div>
</template>

5.2 高阶组件与渲染委托

作用域插槽可以用于实现高阶组件模式，将复杂的渲染逻辑委托给父组件：

vue

复制下载

<!-- DataProvider.vue -->
<template>
  <div>
    <slot :data="data" :loading="loading" :error="error"></slot>
  </div>
</template>

<script>
export default {
  data() {
    return {
      data: null,
      loading: false,
      error: null
    }
  },
  async created() {
    // 获取数据逻辑
  }
}
</script>

5.3 组件库开发中的插槽设计

在组件库开发中，合理的插槽设计可以极大地提高组件的灵活性和可定制性：

  1. 提供合理的默认插槽：确保组件开箱即用
  2. 定义清晰的具名插槽：为常用定制点提供专用插槽
  3. 暴露必要的作用域数据：通过作用域插槽提供组件内部状态
  4. 保持向后兼容：新增插槽不应破坏现有使用方式

六、插槽与其他Vue特性的结合

6.1 插槽与Transition

插槽内容可以应用Vue的过渡效果：

vue

复制下载

<Transition name="fade">
  <slot></slot>
</Transition>

6.2 插槽与Teleport

Vue 3的Teleport特性可以与插槽结合，实现内容在DOM不同位置的渲染：

vue

复制下载

<template>
  <div>
    <slot></slot>
    <Teleport to="body">
      <slot name="modal"></slot>
    </Teleport>
  </div>
</template>

6.3 插槽与Provide/Inject

在复杂组件层级中，插槽可以与Provide/Inject API结合，实现跨层级的数据传递：

vue

复制下载

<!-- 祖先组件 -->
<template>
  <ChildComponent>
    <template v-slot="{ data }">
      <GrandChild :data="data" />
    </template>
  </ChildComponent>
</template>

七、总结与展望

Vue的插槽机制是组件化开发中不可或缺的一部分。从最简单的默认插槽到灵活的作用域插槽，它们共同构成了Vue组件系统的强大内容分发能力。

通过本文的分析，我们可以看到：

  1. 默认插槽提供了基本的内容分发能力，适用于简单的内容替换场景
  2. 作用域插槽实现了数据与表现的彻底分离，为高度可定制的组件提供了可能
  3. 具名插槽解决了多内容区域的组件设计问题

随着Vue 3的普及，插槽API更加统一和强大。组合式API与插槽的结合，为组件设计带来了更多可能性。未来，我们可以期待：

  1. 更优的性能：编译时优化进一步减少插槽的运行时开销
  2. 更好的TypeScript支持：作用域插槽的完整类型推导
  3. 更丰富的生态：基于插槽模式的更多最佳实践和工具库

Vue3 v-if与v-show：销毁还是隐藏，如何抉择？

✇掘金 前端
作者 kknone
2025年12月24日 16:27

1. v-if 与 v-show 的基本概念

条件渲染是Vue3中控制界面显示的核心能力，而v-if和v-show是实现这一能力的两大核心指令。它们的本质差异，要从“**是否真正改变组件的存在 **”说起。

1.1 v-if：真正的“存在与否”

v-if是“破坏性条件渲染”——当条件为true时，它会创建组件实例并渲染到DOM中；当条件为false时，它会销毁 组件实例并从DOM中移除。换句话说，v-if控制的是“组件是否存在”。

举个例子：


<button @click="toggle">切换文本</button>
<div v-if="isShow">Hello, Vue3!</div>

当isShow为false时，你在浏览器DevTools里找不到这个div——它被完全销毁了。而且，组件的生命周期钩子（如onMounted/ onUnmounted）会随着条件切换触发：销毁时执行onUnmounted，重建时执行onMounted。

1.2 v-show：只是“看得见看不见”

v-show是“非破坏性条件渲染”——无论条件真假，它都会先把组件渲染到DOM中，再通过修改CSS的display属性控制可见性。换句话说， v-show控制的是“组件是否可见”，但组件始终存在。

同样的例子，换成v-show：


<button @click="toggle">切换文本</button>
<div v-show="isShow">Hello, Vue3!</div>

当isShow为false时，div依然在DOM中，只是多了style="display: none"。此时，组件实例没有被销毁，生命周期钩子也不会触发——它只是“被藏起来了”。

2. 原理拆解：为什么行为差异这么大？

理解原理是选择的关键，我们用“生活比喻”帮你快速记住：

  • v-if像“客房的家具”：客人来了（条件为真），你把家具搬出来（创建组件）；客人走了（条件为假），你把家具收起来（销毁组件）。每次搬运都要花时间（切换成本高），但平时不占空间（初始化成本低）。
  • v-show像“客厅的电视”：不管你看不看（条件真假），电视都在那里（存在于DOM）；你只是用遥控器（v-show ）切换“显示/隐藏”（修改CSS）。切换动作很快（成本低），但始终占地方（初始化成本高）。

3. 性能对比：初始化 vs 切换成本

v-if和v-show的性能差异，本质是**“空间换时间”还是“时间换空间”**的选择：

3.1 初始化成本：v-if 更“省空间”

当初始条件为false时：

  • v-if：不渲染任何内容，DOM中无节点，初始化速度快；
  • v-show：强制渲染组件，DOM中存在节点，初始化速度慢。

比如，一个“仅管理员可见”的按钮，用v-if更合适——普通用户打开页面时，按钮不会被渲染，减少页面加载时间。

3.2 切换成本：v-show 更“省时间”

当条件需要频繁切换时：

  • v-if：每次切换都要销毁重建组件，涉及DOM操作和生命周期钩子，切换速度慢；
  • v-show：仅修改CSS属性，无DOM重建，切换速度快。

比如， tabs 切换、弹窗显示隐藏，用v-show更流畅——用户点击时不会有延迟。

4. 选择策略：到底该用谁？

结合原理和性能，我们总结了3条黄金法则：

4.1 频繁切换？选v-show！

如果组件需要反复显示/隐藏（如 tabs、弹窗、折叠面板），优先用v-show。比如：

<!-- 频繁切换的弹窗，用v-show -->
<modal v-show="isModalOpen" @close="isModalOpen = false"></modal>

4.2 极少变化？选v-if！

如果条件几乎不会改变（如权限控制、初始化提示），优先用v-if。比如：

<!-- 仅管理员可见的按钮，用v-if -->
<button v-if="isAdmin" @click="deleteItem">删除</button>

4.3 要保留状态？选v-show！

如果组件包含需要保留的状态（如表单输入、播放器进度），必须用v-show——v-if会销毁组件，导致状态丢失。

举个直观的例子：


<template>
    <button @click="toggle">切换输入框</button>
    <!-- v-if：输入内容会重置 -->
    <div v-if="isShow">
        <input type="text" placeholder="v-if 输入框"/>
    </div>
    <!-- v-show：输入内容保留 -->
    <div v-show="isShow">
        <input type="text" placeholder="v-show 输入框"/>
    </div>
</template>

<script setup>
    import {ref} from 'vue'

    const isShow = ref(true)
    const toggle = () => isShow.value = !isShow.value
</script>
往期文章归档
免费好用的热门在线工具

试着输入内容后切换：v-if的输入框会清空（组件销毁），v-show的输入框内容不变（组件存在）。

5. 动手实践：看得到的差异

为了更直观，我们用生命周期钩子验证两者的区别：

  1. 创建子组件Child.vue：

    <template><div>我是子组件</div></template>
<script setup>
import { onMounted, onUnmounted } from 'vue'
onMounted(() => console.log('子组件挂载了！'))
onUnmounted(() => console.log('子组件销毁了！'))
</script>

  2. 父组件中切换：

    <template>
  <button @click="toggle">切换子组件</button>
  <!-- 用v-if时，切换会打印日志 -->
  <Child v-if="isShow" />
  <!-- 用v-show时，切换无日志 -->
  <!-- <Child v-show="isShow" /> -->
</template>

<script setup>
import { ref } from 'vue'
import Child from './Child.vue'
const isShow = ref(true)
const toggle = () => isShow.value = !isShow.value
</script>

运行后点击按钮：

  • 用v-if：切换会打印“子组件销毁了！”和“子组件挂载了！”（组件生死轮回）；
  • 用v-show：无日志（组件始终存在）。

6. 课后Quiz：巩固你的理解

问题：你在开发“用户设置”页面，其中“高级设置”面板可以点击“展开/收起”切换。面板包含多个输入框（如“个性签名”），需要保留用户输入。请问该用 v-if还是v-show？为什么？

答案解析：
用v-show。原因有二：

  1. 频繁切换：用户可能多次展开/收起，v-show切换成本更低；
  2. 状态保留：输入框需要保留内容，v-show不会销毁组件，状态不会丢失。

7. 常见报错与解决

使用v-if/v-show时，这些“坑”要避开：

问题1：v-show 不能和 v-else 一起用

报错：v-else can only be used with v-if
原因：v-else是v-if的配套指令，v-show是CSS控制，无法配合。
解决：用v-if代替v-show，或分开写v-show：

<!-- 错误 -->
<div v-show="isShow">内容A</div>
<div v-else>内容B</div>

<!-- 正确：用v-if -->
<div v-if="isShow">内容A</div>
<div v-else>内容B</div>

<!-- 正确：分开写v-show -->
<div v-show="isShow">内容A</div>
<div v-show="!isShow">内容B</div>

问题2：v-if 和 v-for 一起用导致性能低

报错场景：同一个元素同时用v-if和v-for：


<li v-for="item in list" v-if="item.isActive">{{ item.name }}</li>

原因：Vue3中v-for优先级高于v-if，会先循环所有元素，再逐个判断条件，重复计算导致性能差。
解决：用computed先过滤数组：


<template>
    <li v-for="item in activeItems" :key="item.id">{{ item.name }}</li>
</template>

<script setup>
    import {ref, computed} from 'vue'

    const list = ref([/* 数据 */])
    // 先过滤出active的item
    const activeItems = computed(() => list.value.filter(item => item.isActive))
</script>

问题3：v-show 对 template 无效

报错场景：用v-show控制<template>标签：


<template v-show="isShow">
    <div>内容</div>
</template>

原因：<template>是Vue的虚拟标签，不会渲染成真实DOM，v-show无法修改其display属性。
解决：用真实DOM元素（如<div>）包裹，或用<template v-if>：

<!-- 正确：用div包裹 -->
<div v-show="isShow">
    <div>内容</div>
</div>

<!-- 正确：用v-if -->
<template v-if="isShow">
    <div>内容</div>
</template>

8. 参考链接

参考链接：vuejs.org/guide/essen…

Vue单页应用路由404问题：服务器配置与Hash模式解决方案

✇掘金 前端
作者 JimmyWhat
2025年12月24日 16:03

引言

在Vue单页应用（SPA）部署过程中，用户常遇到直接访问非首页路由返回404的问题。例如访问aaa.com/contract返回404，而通过前端重定向访问aaa.com→/contract却正常。该问题本质是服务器未正确处理前端路由路径，本文将系统梳理解决方案。

问题根源分析

核心原因

  • 前端路由机制：Vue Router通过redirect实现路径跳转，此过程由浏览器处理，无需服务器参与。

  • 服务器行为差异：直接访问/contract时，服务器会查找物理文件，因路径不存在返回404。

问题场景 根本原因 典型表现
直接访问/contract 404 服务器未配置路由回退规则 非首页路由刷新或直接访问失败
前端重定向正常 路径跳转由Vue Router接管 通过首页跳转可正常访问

解决方案详解

方案一：服务器配置回退规则

Nginx配置

nginx
复制
server {
    listen 80;
    server_name aaa.com;
    root /path/to/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;  # 关键配置
    }
}

配置说明：

  • try_files指令按顺序查找文件，若均不存在则返回index.html
  • 适用于所有非静态资源请求，确保前端路由接管路径处理

Apache配置（.htaccess）

apache
复制
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^index.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]
</IfModule>

配置说明：

  • RewriteCond排除真实文件和目录
  • RewriteRule将所有未知路径重写到index.html

Node.js Express配置

JavaScript
复制
const express = require('express');
const path = require('path');
const app = express();

app.use(express.static(path.join(__dirname, 'dist')));
app.get('*', (req, res) => {
    res.sendFile(path.join(__dirname, 'dist', 'index.html'));
});

app.listen(3000);

配置说明：

  • app.get('*')捕获所有路由请求
  • 静态资源中间件确保CSS/JS文件可访问

方案二：启用Hash模式

修改路由配置启用Hash模式，无需服务器配置：

JavaScript
复制
import Vue from 'vue';
import VueRouter from 'vue-router';

Vue.use(VueRouter);

const router = new VueRouter({
    mode: 'hash',  // 启用Hash模式
    routes: [
        { path: '/', redirect: '/contract' },
        {
            path: '/contract',
            name: 'contract',
            component: () => import('../views/contract/index.vue')
        }
    ]
});

export default router;

效果对比：

路由模式 URL格式 服务器要求 适用场景
History模式 /contract 需配置回退规则 美观路由需求
Hash模式 /#/contract 无需配置 快速部署场景

方案三：静态资源路径修正

确保vue.config.js配置正确publicPath：

JavaScript
复制
module.exports = {
    publicPath: process.env.NODE_ENV === 'production' ? '/' : '/',
    // 其他配置...
};

配置说明：

  • 生产环境设为根路径/，避免资源加载失败
  • 开发环境可保持默认值

验证与排查

验证步骤

  1. 部署后测试：

    • 直接访问aaa.com/contract，应正常显示页面
    • 刷新页面，确保不返回404

  2. 控制台检查：

    • 浏览器开发者工具中无404错误
    • 网络请求中所有资源返回200状态码

常见问题排查

  1. Nginx配置未生效：

    • 执行nginx -t测试配置语法
    • 重启Nginx：systemctl restart nginx

  2. Hash模式URL不美观：

    • 需改用History模式并配置服务器

  3. 动态路由参数丢失：

    • 路由配置中设置props: true或通过this.$route.params.id获取

总结

Vue单页应用路由404问题的本质是服务器未正确处理前端路由路径。解决方案包括：

  1. 服务器配置回退规则（Nginx/Apache/Node.js）
  2. 启用Hash模式（无需服务器配置）
  3. 修正静态资源路径（确保publicPath正确）

建议优先采用服务器配置方案，可获得更美观的URL格式。若无法修改服务器配置，Hash模式是可靠备选方案。部署后务必验证所有路由的直接访问和刷新场景，确保无404错误发生。

ElementUI：表格如何展示超出单元格的内容且不影响单元格？

✇掘金 前端
作者 simon9124
2025年12月24日 15:09

关注前端小讴，阅读更多原创技术文章

  • 这个问题之前在封装表格行内编辑校验时就一直困扰我，近期因为业务需求又不得不面对了

需求详述

  • ElementUi表格列若干（肯定有横向滚动条），在若干行（不固定）的某一列上（不固定）展示指定文字，
  • 要展示的文字长度大概率比该列宽度大
  • 文字需要完整展示，可跨单元格

尝试过程

  • 直接使用自定义渲染单元格，失败，超出单元格部分会被遮盖
  • 自定义指令在document上渲染内容，失败，定位很困难（很难拿到该单元格相对整个document的位置），且内容也不随滚动条滚动
  • 使用el-tooltip，让其一直保持展示，失败，el-tooltip初始化没有定位，只有在鼠标移入时才有

成功方案

  • 使用el-popover弹出框的手动激活方式，其既保证dom结构在单元格里，又能打破内容无法超出单元格的壁垒
<template>
  <el-table-column
    v-for="(column, i) in columnList"
    :key="column.value"
    width="20"
    class-name="gantt-column"
  >
    <template slot-scope="scope">
      <div class="gantt-bar" :style="`background: green`">
        <el-popover
          v-if="scope.row.percent"
          v-model="visible"
          popper-class="gantt-percent-popover"
          trigger="manual"
          :content="`${scope.row.percent}%`"
        >
        </el-popover>
      </div>
    </template>
  </el-table-column>
</template>

<script>
export default {
  data() {
    return {
      columnList: [], // 动态表格列
      visible: true, // popover-始终展示
    };
  },
};
</script>

<style lang="scss">
.gantt-percent-popover {
  width: max-content;
  min-width: auto;
  border: none;
  box-shadow: none;
  background: none;
  padding: 0 !important;
  font-size: 14px;
  color: rgba(0, 0, 0, 1);
  font-weight: bold;
  // text-shadow: 1px 1px 1px rgba(0, 0, 0, 0.5);
  white-space: nowrap;
  height: 23px;
  line-height: 23px;
  transform: translate(-40%, 0);
  font-style: italic;
}
</style>

子组件和父组件之间优雅通信---松耦合

✇掘金 前端
作者 快乐星球喂
2025年12月24日 14:52

1、传统的写法

// 父组件
<!-- 父组件 -->
<template>
  <ChildComponent 
    @tabActiveFn="onTabActiveUpdate"
  />
  <button @click="goOrder"></button>
</template>

<script>
export default {
  methods: {
    refresh() {
      console.log('刷新数据');
    },
    onTabActiveUpdate(newValue) {
      this.tabActive = newValue;
      this.refresh();
    },
     goOrder(){
        this.$router.replace({ name: 'order' });
    },
  }
}
</script>

// 子组件
<!-- 子组件 -->
<template v-for="(item, index) in TAB">
  <span :key="index" :class="[tabActive === item.index ? 'active' : 'tab']" @click="changeTab(item)"> {{ item.name }}</span>
  <button @click="goOrder"></button>
</template>

<script>
export default {
data() {
    return {
      tabActive: 1,
      TAB: [
        { index: 1, name: 'xxx服务' },
        { index: 2, name: 'xxx服务' }
      ],
  },
  methods: {
    changeTab(item) {
      this.$emit('tabActiveFn', item.index);
      this.tabActive = item.index;
    },
     goOrder(){
        this.$router.replace({ name: 'order' });
    },
  }
}
</script>

2、使用语法糖

  • （1）父组件定义一个万能方法onInvoke(action) { this[action]?.(); }，根据传入的字符串调用对应方法。
  • （2）父组件通过自定义事件@invokeFn<ChildComponent @invokeFn="onInvoke"/>暴露给子组件。
  • （3）子组件<button @click="$emit('invokeFn', 'goOrder')"></button>，点击时，触发父组件invokeFn事件并传值goOrder
  • （4）父组件收到事件，执行onInvoke('goOrder')，最终安全调用goOrder方法。
// 父组件
<!-- 父组件 -->
<template>
  <ChildComponent 
    @tabActiveFn="onTabActiveUpdate"
    @invokeFn="onInvoke"
  />
</template>

<script>
export default {
  methods: {
    refresh() {
      // 刷新数据
      console.log('刷新数据');
    },
    onTabActiveUpdate(newValue) {
      this.tabActive = newValue;
      this.refresh();
    },
    goOrder(){
        this.$router.replace({ name: 'order' });
    },
    onInvoke(action) {
      this[action]?.();
    },
  }
}
</script>

// 子组件
<!-- 子组件 -->
<template v-for="(item, index) in TAB">
  <span :key="index" :class="[tabActive === item.index ? 'active' : 'tab']" @click="changeTab(item)"> {{ item.name }}</span>
  <button @click="$emit('invokeFn', 'goOrder')"></button>
</template>

<script>
export default {
data() {
    return {
      tabActive: 1,
      TAB: [
        { index: 1, name: 'xxx服务' },
        { index: 2, name: 'xxx服务' }
      ],
  },
  methods: {
    changeTab(item) {
      this.$emit('tabActiveFn', item.index);
      this.tabActive = item.index;
    }
  }
}
</script>

其中，this.[action]，使用方括号语法，动态的访问当前对象（this）上名为action变量值的属性或者方法。例如：action是‘goOrder’,它就试图获取this.goOrder。

?()是可选链操作符和函数的结合，如果this.[action]的值不是null或者undefined，则调用该函数；如果是，则整个表达式短路，返回undefined，而不会抛出错误。

可选链?.是ES2020中引入的一个非常实用的语法。它的核心价值是在于防止在访问嵌套属性或者方法时，因中间某个值为null或者undefined而导致运行时错误。

优点：松耦合，子组件完全不需要知道父组件具体有哪些方法，它只需要知道自己需要触发什么指令。父组件则负责接收指令并执行对应的逻辑，这使得子组件的复用性非常高，可以轻松被不同父组件使用，只要这些父组件都实现了相应的指令并监听了对应的事件即可。

回顾计算属性的缓存与监听的触发返回结果

✇掘金 前端
作者 拉不动的猪
2025年12月23日 17:13

前言

网上的给出的区别有很多，今天只是简单来回归下其中的一些流程和区别的关键点。

以下面的代码为例进行思考：

<template>
  <div class="calc">
    <input v-model.number="n1" type="number" placeholder="数字1">
      <input v-model.number="n2" type="number" placeholder="数字2">
        <p>和：{{ sum }} 平均值：{{ avg }}</p>
        <input v-model="name" placeholder="用户名">
          <p :style="{color: tipColor}">{{ tip }}</p>
        </div>
</template>

<script>
  export default {
    data() {
      return { n1: 0, n2: 0, name: '', tip: '', tipColor: '#333' }
    },
    computed: {
      sum() { return this.n1 + this.n2 },
      avg() { return this.sum / 2 }
    },
    watch: {
      name(v) {
        if (!v.trim()) { this.tip = '不能为空'; this.tipColor = 'red' }
        else if (v.length < 3) { this.tip = '不少于3位'; this.tipColor = 'orange' }
        else { this.tip = '可用'; this.tipColor = 'green' }
      }
    }
  }
</script>

<style scoped>
  .calc { padding: 20px; border: 1px solid #eee; width: 300px; margin: 20px auto; }
  input { display: block; width: 100%; margin: 8px 0; padding: 6px; border: 1px solid #ccc; border-radius: 4px; }
</style>

关于 watch 和 computed 的使用我们很多，这里我们不一一介绍，但是请记住：监听是不需要 return 的，计算属性是百分百必须要有的。

1、监听和计算属性的区别

最关键的区别：

1、监听是没有缓存的，计算属性是有缓存的

2、监听是不需要有返回值的，但是机损属性是必须要有返回值的。（极限情况下不return基本没意义）

其他的区别：

对比维度 计算属性（computed） 监听器（watch）
核心用途 基于已有数据推导 / 计算新数据（数据转换 / 组合） 监听已有数据的变化，执行异步操作或复杂逻辑（无新数据产出，侧重 “副作用”）
依赖关系 只能依赖 Vue 实例中的响应式数据（data/props/ 其他 computed），自动感知依赖变化 可监听单个响应式数据、对象属性、数组，甚至通过 deep: true监听对象深层变化，支持手动指定监听目标
使用场景 1. 简单数据拼接（如全名：firstName + lastName）2. 数据格式化（如时间戳转日期字符串）3. 依赖多数据的计算（如总价：price * count）4. 需缓存的重复计算场景 1. 异步操作（如监听输入框变化，延迟请求接口获取联想数据）2. 复杂逻辑处理（如监听用户状态变化，同步更新权限菜单）3. 监听对象深层变化（如监听表单对象，统一处理提交前校验）4. 数据变化后的联动操作（非数据推导类）
是否支持异步 不支持异步操作：若在 computed中使用异步（如定时器、接口请求），无法正确返回推导结果，会得到 undefined 支持异步操作：这是 watch的核心优势之一，可在监听函数中执行任意异步逻辑

2： 监听和计算属性的基本触发流程：

核心逻辑：set → Dep → Watcher → watch/computed 联动流程

无论是 watch 还是 computed，底层联动流程的核心一致，仅在 Watcher 执行逻辑上有差异，完整流程如下：

第一步：初始化阶段 —— 依赖收集（get 拦截器 + Dep + Watcher 绑定）

  1. computed ****的依赖收集：
  1. 组件初始化时，会为每个计算属性创建一个「计算属性 Watcher」； 1. 执行计算属性的 get 方法，访问依赖的响应式数据（如 this.num1）； 1. 触发该数据的 get 拦截器，get 拦截器会将当前「计算属性 Watcher」添加到该数据的 Dep 依赖列表中； 1. 所有依赖数据都完成 Watcher 绑定，最终缓存计算属性的初始结果。
  1. watch ****的依赖收集：
    1. 组件初始化时，会为每个 watch 监听目标创建一个「普通 Watcher」；
    2. 主动读取一次监听目标数据（如 this.username），触发该数据的 get 拦截器；
    3. get 拦截器将当前「普通 Watcher」添加到该数据的 Dep 依赖列表中；
    4. 若开启 deep: true，会递归遍历对象 / 数组的内部属性，完成深层依赖收集。

第二步：更新阶段 ——set 拦截器触发 Watcher 执行

当修改响应式数据时（如 this.num1 = 10），触发底层联动：

  1. 数据被修改，触发该数据的 set 拦截器；
  2. set 拦截器调用对应 Dep 的 notify() 方法（派发更新通知）；
  3. Dep 遍历自身的依赖列表，通知所有绑定的 Watcher「数据已更新」；
  4. 不同类型的 Watcher 接收通知后，执行差异化操作（这是 watch 和 computed 表现不同的核心原因）：
    • 普通 Watcher （对应 watch ） ：收到通知后，立即执行 watch 的回调函数，传入 newVal 和 oldVal，执行异步 / 复杂逻辑；
    • 计算属性 Watcher （对应 computed ） ：收到通知后，仅将自身标记为「脏状态」（缓存失效） ，不立即执行计算逻辑，等待下次访问计算属性时，才重新执行 get 方法计算新结果并更新缓存。

举个例子：

  watch: {
    num(newVal, oldVal) {
      console.log(`【watch】：num从${oldVal}变为${newVal}，我立即执行回调`);
    }
  },

当 set 触发 watcher 后，watcher 就会立即触发：

num(newVal, oldVal) {
      console.log(`【watch】：num从${oldVal}变为${newVal}，我立即执行回调`);
    }

什么叫 收到通知后， 仅将自身标记为「脏状态」（缓存失效） ，不立即执行计算逻辑，等待下次访问计算属性时，才重新执行 get 方法计算新结果并更新缓存。

举个例子：

<template>
  <div>
    <!-- 这里就是「访问计算属性」：模板渲染时会读取 numDouble 的值 -->
    <p v-if="num < 2">两倍数：{{ numDouble }}</p>
  </div>
</template>

<script>
export default {
  data() {
    return { num: 1 };
  },
  computed: {
    numDouble() {
      console.log("计算属性执行计算");
      return this.num * 2;
    },
  },
  mounted() {
    setTimeout(() => {
    this.num = 5; // 2秒后，v-if不成立
  }, 2000);
  setTimeout(() => {
    this.num = 1; // 4秒后，v-if再次成立
  }, 4000);
  },
};
</script>

// 控制台只会打印2次“计算属性执行

为什么只打印 2 次：

原因就是我们的计算属性在 2s 后没有执行

1、 当初始化时，页面中 v-if 条件是符合的，会执行一次 get 计算得到返回值

2、当经过两秒后、 v-if 不符合条件，这个时候表明numDouble 是脏数据，会对其进行标记（ v-if 不符合条件，所以无法对numDouble 进行访问， 这里也就是我们说的缓存，缓存计算属性的结果值，当脏状态取消时才会进行新的计算 )

3、当 经过 4 秒后条件再次被满足时，才会有新的计算。

3： 计算属性为什么不能异步

举个例子，我们使用延时进行模仿：

<template>
  <div>
    <!-- 这里就是「访问计算属性」：模板渲染时会读取 numDouble 的值 -->
    <p v-if="num < 2">两倍数：{{ numDouble }}</p>
  </div>
</template>

<script>
export default {
  data() {
    return { num: 1 };
  },
  computed: {
    numDouble() {
      setTimeout(() => {
        return this.num * 2;
      }, 1000);
    },
  },
  mounted() {
    console.log(this.numDouble);
  },
};
</script>

打印结果如下：

为什么会打印 underfined 呢，这里有两个原因？

原因 1：JavaScript 中，任何函数如果没有显式写 return 语句，或 return 后没有跟随具体值，都会默认返回 undefined，这是计算属性返回 undefined 的基础原因。

举个例子：

function test() {
        setTimeout(() => {
          return 11;
        }, 1000);
      }
      setTimeout(() => {
        console.log(test());
      }, 2000);

这样写是属于语法的错误。

原因 2：setTimeout 的异步特性（关键）

即使你在 setTimeout 回调中写了 return this.num * 2，这个返回值也毫无意义，因为 setTimeout是异步宏任务：

  1. 当 Vue 访问 this.numDouble 时，会立即执行计算属性的函数体；
  2. 函数体执行到 setTimeout 时，只会「注册一个异步任务」，然后直接跳过 setTimeout 继续执行；
  3. 此时计算属性函数体已经执行完毕（没有显式 return），默认返回 undefined，并被 console.log 打印；
  4. 1 秒后，setTimeout 的回调函数才会执行，此时回调中的 return this.num * 2 只是回调函数自身的返回值，无法传递给计算属性，也无法改变之前已经返回的 undefined。

简单说：异步回调的返回值，无法成为计算属性的返回值，计算属性会在异步任务注册后，直接默认返回 undefined 。

也可以分两步走

一、先明确：计算属性的函数体，只在 “被访问” 时同步执行一次（除非满足重新计算条件）

当 mounted 中访问 this.numDouble，或者模板渲染访问 numDouble 时，Vue 会同步、完整地执行一遍 ****numDouble ****函数体的代码，但这个执行过程和 setTimeout 内部的回调是完全分离的：

第一步：计算属性函数体「同步执行」（瞬间完成，不等待异步）

我们把 numDouble 的执行过程拆解成 “逐行执行”，你就能看清流程：

numDouble() {
  // 第1步：执行 setTimeout 这行代码
  // 作用：向浏览器“注册一个1秒后执行的异步任务”，仅此而已
  // 注意：这行代码执行时，不会等待1秒，也不会执行回调函数内部的代码
  setTimeout(() => {
    // 这是回调函数，此时完全没有执行！
    console.log("回调函数开始执行");
    return this.num * 2;
  }, 1000);

  // 第2步：计算属性函数体执行到末尾
  // 没有显式 return，默认返回 undefined
  // 此时，numDouble 已经完成了“返回值”的传递，整个函数体执行结束
}

简单来说就是numDouble 函数体的执行，只做了一件事 ——“安排了一个 1 秒后的任务”，然后就直接返回了 undefined，它不会停下来等 1 秒后回调执行完再返回值。

第二步：1 秒后，异步回调才执行，但为时已晚

  1. 计算属性已经在第一步就返回了 undefined，这个返回值已经被 console.log 打印，也被 Vue 缓存起来了；
  2. 1 秒后，浏览器才会执行 setTimeout 的回调函数，此时回调里的 return this.num * 2 只是 “回调函数自己的返回值”—— 这个值没有任何接收者，既不能传给 numDouble ，也不能改变之前已经返回的 undefined ；
  3. 更关键的是：回调执行时，numDouble 函数体早就执行完毕了，两者是完全独立的执行流程，回调的返回值无法 “回溯” 给已经执行完的计算属性。

简单来讲就是：

计算属性是要内置返回一个结果的，如果加入异步就会因为执行顺讯返回一个undefined，监听是在事件触发后对写入的回调函数的调用。

为什么vue中使用query可以保留参数

✇掘金 前端
作者 周星星日记
2025年12月22日 17:04

本质与原理

一句话回答：
这是 Vue Router 将 query 对象序列化为 URL 查询字符串（Query String） ，并拼接到路径后面，形成完整的 URL（如 /user?id=123&name=alice），从而实现参数传递。

本质：前端路由对 URL 的构造与解析

Vue Router 并不“保存”参数，而是：

  1. 构造一个合法的 URL
  2. 通过浏览器 History API 或 hash 变更 URL
  3. 在路由匹配时反向解析该 URL

所以，query 的存在完全依赖于 URL 本身的结构。

🛠 执行过程详解

当你调用：

this.$router.push({
  path: '/user',
  query: { id: 123, name: 'alice' }
});

Vue Router 内部会执行以下步骤：

1：序列化 query 对象

  • 使用类似 URLSearchParams 的机制，将 { id: 123, name: 'alice' } 转为字符串：
// 伪代码
const queryString = new URLSearchParams({ id: 123, name: 'alice' }).toString();
// 结果: "id=123&name=alice"

2：拼接完整 URL

  • 将 path 和 queryString 合并：
/user + ? + id=123&name=alice → /user?id=123&name=alice

3：触发 URL 变更

  • 根据当前模式（hash 或 history）：
    • Hash 模式：设置 location.hash = '#/user?id=123&name=alice'
    • History 模式：调用 history.pushState(null, '', '/user?id=123&name=alice')

✅ 此时，浏览器地址栏显示完整带参 URL，且页面不刷新。

4：路由匹配与参数注入

  • Vue Router 监听到 URL 变化后：
    • 匹配路由（如 { path: '/user', component: User }）
    • 解析查询字符串，还原为对象：

this.$route.query === { id: "123", name: "alice" }

⚠️ 注意：所有 query 值都是 字符串类型（HTTP 协议限制）

为什么可以“带上路径后面”？

因为这是 URL 标准的一部分！

根据 RFC 3986，URL 结构如下：



https://example.com/user?id=123&name=alice
│          │        │     └───────────────┘
│          │        │           ↑
│          │        │     Query String（查询字符串）
│          │        └── Path（路径）
│          └── Host（主机）
└── Scheme（协议）
  • 查询字符串（ ?key=value&... ）是 URL 的合法组成部分
  • 浏览器天然支持它，刷新时会完整保留
  • 服务端和前端都可以读取它

💡 Vue Router 只是利用了这一标准机制，并没有发明新东西。

优势：为什么推荐用 query 传参？

特性 说明
可分享 完整 URL 可直接复制发送给他人
可刷新 刷新后参数仍在（因为 URL 没变）
可书签 用户可收藏带参链接
SEO 友好 搜索引擎能索引不同 query 的页面（如搜索结果页）
调试方便 地址栏直接可见参数

注意事项

  1. 值类型全是字符串

// 传入
query: { id: 123 } // number
// 接收
this.$route.query.id === "123" // string!

需要手动转换：parseInt(this.$route.query.id)

  1. 敏感信息不要放 query
    • 查询字符串会出现在：
      • 浏览器历史记录
      • 服务器日志
      • Referer 头（如果跳转到第三方）
    • 不适合放 token、密码等
  1. 长度有限制
    • URL 总长一般限制在 2048 字符以内（各浏览器不同）
    • 大量数据建议用 POST 或状态管理

对比：query vs params（非路径型）

方式 是否体现在 URL 刷新后保留 适用场景
query ✅ 是（?id=123） ✅ 是 公开、可分享、可刷新的参数
params（未在 path 声明） ❌ 否 ❌ 否 临时跳转（如表单步骤），但刷新丢失

总结

this.$router.push({ path: '/user', query: {...} }) 的本质是：
构造一个标准的、带查询字符串的 URL，并通过前端路由机制导航到该地址。

  • 它利用的是 URL 原生的查询参数机制
  • 参数被持久化在地址栏中，因此刷新不丢失
  • 这是 SPA 应用中最安全、最通用的传参方式之一

🌟 记住：只要参数需要“跨刷新”或“可分享”，优先用 query ！

现代前端开发工程化：从 Vite 到 Vue 3 多页面应用实战

✇掘金 前端
作者 Tzarevich
2025年12月22日 16:46

现代前端开发工程化：从 Vite 到 Vue 3 多页面应用实战

在当今快速迭代的前端开发环境中，工程化已成为构建高质量、可维护项目的基石。本文将结合实际项目结构与开发流程，带你深入理解如何使用 Vite 搭建一个现代化的 Vue 3 项目，并实现多页面路由功能，打造高效、优雅的前端开发体验。

一、什么是 Vite？为何它如此重要？

Vite 是由 Vue 作者尤雨溪主导开发的新一代前端构建工具，它颠覆了传统打包工具（如 Webpack）的“先打包再运行”模式，转而利用浏览器原生支持的 ES 模块（ESM），实现了：

  • ✅ 极速冷启动：无需等待打包，项目秒级启动；
  • ✅ 毫秒级热更新（HMR） ：修改代码后浏览器自动刷新，开发效率翻倍；
  • ✅ 开箱即用的现代特性：对 TypeScript、CSS 预处理器、JSX 等天然支持；
  • ✅ 轻量且高性能：基于 Node.js 构建，但不干扰开发阶段的加载逻辑。

简单来说，Vite 是现代前端开发的“加速器” ，让开发者专注于业务逻辑，而非等待编译。

二、初始化项目：npm init vite

打开终端，执行以下命令创建新项目：

npm init vite@latest my-vue-app -- --template vue
cd my-vue-app
npm install

这会生成一个标准的 Vue 3 + Vite 项目模板。运行：

npm run dev

项目将在 http://localhost:5173 启动，并自动打开浏览器，进入开发环境。此时 Vite 已作为开发服务器运行：它不会打包整个应用，而是按需通过原生 ESM 加载模块。当你访问 localhost:5173 时，浏览器直接请求 /src/main.js，Vite 在后台实时解析 .vue 文件并提供模块服务——这正是“无需打包即可开发”的核心机制。

📌 注意：确保安装 Volar 插件（VS Code 官方推荐），以获得 Vue 3 的语法高亮、智能提示和代码补全；同时安装 Vue Devtools 浏览器插件用于调试组件状态。

三、项目架构解析

以下是典型的 Vite + Vue 3 项目结构：

vitevue.png

my-vue-app/
├── index.html              # 入口 HTML 文件
├── src/
│   ├── assets/             # 静态资源（图片、SVG 等）
│   ├── components/         # 可复用组件
│   │   └── HelloWorld.vue
│   ├── router/             # 路由配置
│   │   └── index.js
│   ├── views/              # 页面级组件
│   │   ├── Home.vue
│   │   └── About.vue
│   ├── App.vue             # 根组件
│   ├── main.js             # 应用入口
│   └── style.css           # 全局样式
├── public/                 # 公共静态资源（不会被构建处理）
├── package.json            # 依赖与脚本配置
├── vite.config.js          # Vite 配置文件（可选）
└── .gitignore

关键点说明：

Vue 应用的启动流程如下：浏览器加载 index.html → 执行 <script type="module" src="/src/main.js"> → main.js 调用 createApp(App) 创建实例 → 将根组件 App.vue 挂载到 #root 元素。整个过程由 Vite 提供的 ESM 环境驱动，无需传统打包步骤。

  • index.html：Vite 默认以此为入口，其中 <div id="root"></div> 是 Vue 应用的挂载点。
  • main.js：创建 Vue 实例并挂载到 #root。
  • App.vue：整个应用的根组件，所有内容由此展开。
  • src/components/ ：存放通用组件，如按钮、表单等。
  • src/views/ ：存放页面级组件，每个页面对应一个 .vue 文件。
  • src/router/index.js：路由配置中心。

这种目录划分体现了现代前端工程化的核心思想：

  • 关注点分离：页面（views）、通用组件（components）、路由（router）各司其职；
  • 可扩展性：新增功能只需在对应目录添加文件，不影响整体结构；
  • 团队协作友好：开发者可并行开发不同模块，降低耦合风险。

四、实现多页面：引入 Vue Router

在单页应用（SPA）中，“多页面”其实是通过路由切换不同的视图组件。我们使用 Vue Router 来实现这一功能。

1. 安装 vue-router

npm install vue-router@4

⚠️ 注意：Vue 3 必须搭配 vue-router v4。

2. 创建页面组件

在 src/views/ 下创建两个页面：

Home.vue

<template>
  <div>
    <h1>首页</h1>
    <p>欢迎来到主页！</p>
  </div>
</template>

About.vue

<template>
  <div>
    <h1>关于</h1>
    <p>这里是关于我们页面。</p>
  </div>
</template>

3. 配置路由

在 src/router/index.js 中配置路由：

import { createRouter, createWebHashHistory } from 'vue-router'
import Home from '../views/Home.vue'
import About from '../views/About.vue'

const routes = [
  { path: '/', component: Home },
  { path: '/about', component: About }
]

const router = createRouter({
  history: createWebHashHistory(),
  routes
})

export default router

💡 使用 createWebHashHistory() 可以避免服务器配置问题，适合本地开发。

4. 注册并使用路由

修改 main.js：

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import './style.css'

createApp(App).use(router).mount('#root')

修改 App.vue 添加导航和路由出口：

<template>
  <nav>
    <router-link to="/">首页</router-link> |
    <router-link to="/about">关于</router-link>
  </nav>
  <router-view />
</template>

现在，点击链接即可在不同页面间切换，URL 也会相应变化，完全符合 SPA 的交互体验。

五、总结：现代前端工程化的核心价值

  • 极速开发体验： 借助 Vite 利用浏览器原生 ES 模块（ESM）的能力，实现项目秒级冷启动和毫秒级热更新，大幅减少等待时间。

  • 组件化开发模式： Vue 3 的单文件组件（.vue）结构将模板、逻辑与样式封装在一起，提升代码复用性与可维护性。

  • 清晰的项目结构： 标准化的目录组织（如 src/views/、src/components/、src/router/）让项目职责分明，便于团队协作和长期维护。

  • 路由管理能力： 通过官方插件 vue-router 实现声明式路由配置，轻松支持多页面（视图）切换，构建完整的单页应用（SPA）。

  • 强大的工具生态支持：

    • Volar：提供 Vue 3 专属的语法高亮、智能提示和类型检查；
    • Vue Devtools：在浏览器中直观调试组件状态、路由和事件流。

  • 低门槛、高扩展性： 从 npm init vite 一行命令即可生成完整项目骨架，后续可无缝集成 TypeScript、Pinia、单元测试、自动化部署等高级能力。

  • 面向未来的架构设计： 整套工程化方案基于现代 Web 标准构建，兼顾开发效率与生产性能，为构建复杂企业级应用打下坚实基础。

六、结语

前端工程化不是炫技，而是让开发更高效、更可靠、更可持续的过程。从 npm init vite 开始，你已经迈入了现代前端开发的大门。掌握 Vite、Vue 3 和 vue-router，你就拥有了构建复杂应用的核心能力。

🚀 接下来，不妨尝试添加一个表单、引入 Pinia 管理用户登录状态，或者部署到 GitHub Pages —— 让你的第一个现代前端项目真正落地！

代码是思想的体现，工程化是思想的容器。愿你在前端之路上越走越远。

跨域问题详解

✇掘金 前端
作者 学习CS的小白
2025年12月22日 16:39

引言：在一个前/后端分离的项目开发中，常常会出现前端向后端发送一个请求时，浏览器报错：Access to XMLHttpRequest at 'http://localhost:8080/' from origin 'http://localhost:3000' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.，也就是通常说的“跨域访问”的问题，由此导致前端代码不能读取到后端数据。

摘要：所谓“跨域问题”，本质上是浏览器在同源策略约束下，主动阻止 JavaScript 读取跨源请求响应的一种安全保护行为。解决跨域问题主要通过服务器端设置CORS（跨域资源共享）机制——浏览器放行跨域请求响应的数据；或者Nginx/网关的代理功能——跨域的请求实际由网关代发，浏览器端依旧是同源请求。

什么是跨域访问

跨域访问指的是：当前网页所在的“源（Origin）”去访问另一个“不同源”的资源，而该访问被浏览器安全策略所限制或拦截的情况。

在浏览器中一个“源”由三部分组成：协议（Protocol） + 域名（Host） + 端口（Port），只要有一个部分不一样就是跨源，也即跨域。例如：

URL 协议 域名 端口 是否同源
http://example.com http example.com 80 基准
http://example.com:8080 http example.com 8080 跨域（端口不同）
https://example.com https example.com 443 跨域（协议不同）
http://api.example.com http api.example.com 80 跨域（域名不同）

这里需要强调：对“跨域访问”进行限制是浏览器的安全策略导致的，并不是前端或后端技术框架引起的。

为什么跨域访问请求“得不到”数据

这里就要展开说明为什么浏览器要对“跨域访问”进行限制，导致（尤其是）Web前端中发送HTTP请求会得不到数据，并在控制台报错。

出于安全性，浏览器会采用同源策略（Same-Origin Policy，SOP）限制脚本内发起的跨源 HTTP 请求，限制一个源的文档或者它加载的脚本如何与另一个源的资源进行交互。它能帮助阻隔恶意文档，减少可能被攻击的媒介。例如，它可以防止互联网上的恶意网站在浏览器中运行 JavaScript 脚本，从第三方网络邮件服务（用户已登录）或公司内网（因没有公共 IP 地址而受到保护，不会被攻击者直接访问）读取数据，并将这些数据转发给攻击者。

假设在没有同源限制的情况下：

  • 用户已登录银行网站 https://bank.com（Cookie 已保存）
  • 用户同时打开一个恶意网站 https://evil.com
  • evil.com 的 JavaScript 可以：
    • 直接读取 bank.com 的接口返回数据
    • 发起转账请求
    • 窃取用户隐私信息

这是非常严重的安全灾难。

同源策略将跨源之间的访问（交互）通常分为3种：

  • 跨源写操作（Cross-origin writes）一般是被允许的。例如链接、重定向以及表单提交。特定少数的 HTTP 请求需要添加预检请求。
  • 跨源资源嵌入（Cross-origin embedding）一般是被允许的，比如<img src="...">、<script src="...">、<link href="...">。
  • 跨源读操作（Cross-origin reads）一般是不被允许的。

再次强调：跨域限制是“浏览器行为”，不是后端服务器的限制。后端服务本身是可以接收来自任何来源的 HTTP 请求的。

比如前端访问fetch("https://api.example.com/data")，而当前页面来自http://localhost:8080，请求可以发出去，但浏览器会拦截响应，不让 JavaScript 读取。

要使不同源可以访问（交互），可以使用 CORS来允许跨源访问。CORS 是HTTP的一部分，它允许服务端来指定哪些主机可以从这个服务端加载资源。

怎么解决跨域访问的“问题”

CORS机制

跨源资源共享（Cross-Origin Resource Sharing，CORS，或通俗地译为跨域资源共享）是一种基于HTTP头的机制，该机制通过允许服务器标示除了它自己以外的其他源（域、协议或端口），使得浏览器允许这些源访问加载自己（服务器）的资源。跨源资源共享还通过一种机制来检查服务器是否会允许要发送的真实请求，该机制通过浏览器发起一个到服务器托管的跨源资源的“预检”请求。在预检中，浏览器发送的头中标示有 HTTP 方法和真实请求中会用到的头（Header）。

对那些可能对服务器数据产生副作用的 HTTP 请求方法（特别是GET以外的 HTTP 请求，或者搭配某些MIME类型（多用途互联网邮件扩展，是一种标准，用来表示文档、文件或一组数据的性质和格式）的POST请求），浏览器必须首先使用OPTIONS方法发起一个预检请求（preflight request），从而获知服务端是否允许该跨源请求。服务器确认允许之后，才发起实际的 HTTP 请求。在预检请求的返回中，服务器端也可以通知客户端，是否需要携带身份凭证（例如Cookie和HTTP 认证相关数据）。

一般浏览器要检查的响应头有：

  • Access-Control-Allow-Origin：指示响应的资源是否可以被给定的来源共享。
  • Access-Control-Allow-Methods：指定对预检请求的响应中，哪些 HTTP 方法允许访问请求的资源。
  • Access-Control-Allow-Headers：用在对预检请求的响应中，指示实际的请求中可以使用哪些 HTTP 标头。
  • Access-Control-Allow-Credentials：指示当请求的凭据标记为 true 时，是否可以暴露对该请求的响应给脚本。
  • Access-Control-Max-Age：指示预检请求的结果能被缓存多久。

如：

Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true

可知，若使用CORS解决跨域访问中的问题要在服务器端（通常是后端）进行设置。以Spring Boot的后端为例：

  • 局部的请求：在对应的Controller类或指定方法上使用@CrossOrigin。如下

    @CrossOrigin(
    origins = "http://localhost:3000",
    allowCredentials = "true"
)

  • 全局使用：新建一个配置类并注入Spring框架中。如下：

    @Configuration
public class CorsConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins(
                    "http://test.example.com"
                )
                .allowedMethods("GET","POST","PUT","DELETE")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

使用CORS 的优点：官方标准；安全、可控；与前后端分离完美匹配。缺点：需要服务端正确配置；初学者容易被预检请求困扰。

通过架构或代理手段

除了使用CORS的方式，还可以通过架构设计或代理的方式让跨域“变成”同源访问。

比如通过Nginx / 网关代理浏览器（前端）请求，再由Nginx或网关访问服务器获取数据。

浏览器 → 前端域名 → Nginx → 后端服务

这样的话在浏览器（前端）看到将始终是对当前网站（前端域名）的访问（即使打开开发者工具的网络选项，请求的url地址也是前端域名）。

一个Nginx的配置示例：

server {
    listen 443;
    server_name www.example.com;

    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://backend:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

前端请求示例：axios.get('/api/user')。

这是通过Nginx或网关这样的中间件实现的，如果在开发阶段想要快速解决跨域访问问题，可以在相应的项目构建的配置中设置代理。这里以Vite为构建工具的Vue项目为例，在vite.config.js中添加如下的配置项：

// vite.config.js
export default {
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true
      }
    }
  }
}

然后请求的URL采用这样的方式axios.get('/api/user')，不在使用axios.get('http://localhost:8080/api/user')。

使用代理方式的优点：无跨域；性能好；适合生产环境。缺点：需要额外部署配置。

总结

跨域问题并不是请求被禁止，而是浏览器在同源策略约束下，出于安全考虑，限制前端 JavaScript 对跨源响应数据的访问行为。

跨域问题的根源是 浏览器实现的同源策略（Same-Origin Policy），而不是：

  • HTTP 协议限制
  • 后端服务器限制
  • 前端框架（Vue / React）的问题

浏览器阻止的是JS 获取结果，而不是“阻止请求发送”——跨域请求可以被发出，服务器可以正常返回（比如预检请求响应），浏览器阻止JavaScript访问响应数据。

“跨域问题”只存在于浏览器环境，例如：

  • Java / Node / Python 发 HTTP 请求——没有跨域问题
  • Postman / curl ——没有跨域问题
  • 微服务之间调用——没有跨域问题

因为这些环境不执行浏览器的同源策略。跨域问题是浏览器安全模型的一部分，本质上是对跨源资源访问的“读权限控制”，而非通信能力限制。

使用CORS 并不是“绕过”同源策略——浏览器的同源策略始终存在；CORS 是 同源策略的“例外机制”；本质是：服务器显式授权浏览器放行。换句话说：没有 CORS，就没有“合法的跨域读取”。

只要不产生跨域，就不会有跨域问题，所以可以使用代理或网关将请求进行转发，而不是由浏览器直接请求服务器端发生跨域问题。

用 Vue3 + Coze API 打造冰球运动员 AI 生成器：从图片上传到风格化输出

✇掘金 前端
作者 ohyeah
2025年12月22日 14:56

本文将带你从零构建一个基于 Vue3 和 Coze 工作流的趣味 AI 应用——“宠物变冰球运动员”生成器。通过上传一张宠物照片，结合用户自定义的队服编号、颜色、位置等参数，即可生成一张风格化的冰球运动员形象图。

一、项目背景与目标

在 AI 能力逐渐普及的今天，越来越多开发者尝试将大模型能力集成进自己的 Web 应用中。本项目的目标是打造一个轻量、有趣、可分享的前端应用：

  • 用户上传宠物照片；
  • 自定义冰球队服（编号、颜色）、场上位置（守门员/前锋/后卫）、持杆手（左/右）以及艺术风格（写实、乐高、国漫等）；
  • 后端调用 Coze 平台的工作流 API，完成图像生成；
  • 最终返回生成结果并展示。

这类“趣味换脸/换装”类应用非常适合社交传播，比如冰球协会举办活动时，鼓励用户上传自家宠物照片生成“冰球明星”，再分享至朋友圈，既有趣又具传播性。

二、技术栈与核心流程

技术选型

  • 前端框架：Vue 3（<script setup> + Composition API）
  • 状态管理：ref 响应式变量
  • HTTP 请求：原生 fetch
  • AI 能力平台：Coze（提供工作流和文件上传 API）
  • 环境变量：import.meta.env.VITE_PAT_TOKEN（用于安全存储 PAT Token）

核心业务流程

  1. 图片预览：用户选择图片后，立即在前端显示预览（使用 FileReader + Base64）；
  2. 上传图片：将图片通过 FormData 上传至 Coze 文件服务，获取 file_id；
  3. 调用工作流：携带 file_id 与用户配置参数，调用 Coze 工作流 API；
  4. 展示结果：解析返回的图片 URL 并渲染。

三、代码详解：从模板到逻辑

1. 模板结构（Template）

<template>
  <div class="container">
    <div class="input">
      <!-- 图片上传与预览 -->
      <div class="file-input">
        <img :src="imgPreview" alt="" v-if="imgPreview">
        <input type="file"
         ref="uploadImage" 
         accept="image/*"
         @change="updataImageData"
         required>
      </div>

      <!-- 配置项：队服、位置、风格等 -->
      <div class="settings">
        <div class="selection">
          <label>队服编号:</label>
          <input type="number" v-model="uniform_number">
        </div>
        <div class="selection">
          <label>队服颜色:</label>
          <select v-model="uniform_color">
            <option value="红">红</option>
            <option value="蓝">蓝</option>
            <!-- 其他颜色... -->
          </select>
        </div>
      </div>

      <div class="settings">
        <div class="selection">
          <label>位置</label>
          <select v-model="position">
            <option value="0">守门员</option>
            <option value="1">前锋</option>
            <option value="2">后卫</option>
          </select>
        </div>
        <div class="selection">
          <label>持杆：</label>
          <select v-model="shooting_hand">
            <option value="0">左手</option>
            <option value="1">右手</option>
          </select>
        </div>
        <div class="selection">
          <label>风格：</label>
          <select v-model="style">
            <option value="写实">写实</option>
            <option value="乐高">乐高</option>
            <!-- 多种艺术风格... -->
          </select>
        </div>
      </div>
       
      <!-- 生成按钮 -->
      <div class="generate">
        <button @click="generate">生成</button>
      </div>
    </div>

    <!-- 输出区域 -->
    <div class="output">
      <div class="generated">
        <img :src="imgUrl" alt="" v-if="imgUrl">
        <div v-if="status">{{ status }}</div>
      </div>  
    </div>
  </div>
</template>

✅ 关键点：

  • 使用 v-if 控制预览图和结果图的显示；
  • accept="image/*" 限制仅可选择图片文件；
  • 所有配置项均通过 v-model 双向绑定到响应式变量。

2. 响应式状态声明（Script Setup）

import { ref, onMounted } from 'vue'

const imgPreview = ref('') // 本地预览图（Base64）
const uniform_number = ref(10)
const uniform_color = ref('红')
const position = ref(0)
const shooting_hand = ref('左手') // 注意：实际传给后端的是 0/1，此处为显示用
const style = ref('写实')

// 生成状态与结果
const status = ref('')
const imgUrl = ref('')

// Coze API 配置
const patToken = import.meta.env.VITE_PAT_TOKEN
const uploadUrl = 'https://api.coze.cn/v1/files/upload'
const workflowUrl = 'https://api.coze.cn/v1/workflow/run'
const workflow_id = '7567272503635771427'

🔒 安全提示：VITE_PAT_TOKEN 是 Personal Access Token，绝不能硬编码在代码中！应通过 .env 文件注入，并确保 .gitignore 中排除该文件。

3. 图片预览功能：用户体验的关键

const uploadImage = ref(null)

onMounted(() => {
  console.log(uploadImage.value) // 挂载后指向 input DOM
})
// 状态 null -> input DOM  ref也可以用来绑定DOM元素

const updataImageData = () => {
  const input = uploadImage.value
  if (!input.files || input.files.length === 0) return
  // 文件对象 html新特性
  const file = input.files[0]
  const reader = new FileReader() // 
  reader.readAsDataURL(file)
  // readAsDateURL 返回Base64编码的DataURL 可直接用于<img src>
  reader.onload = (e) => {
    imgPreview.value = e.target.result // // 响应式状态 当拿到图片文件后 立马赋给imgPreview的value 那么此时template中img的src就会接收这个状态 从而响应展示图片
  }
}

🌟 为什么需要预览？

  • 用户上传的图片可能较大，上传需时间；
  • 立即显示预览能提升交互反馈感；
  • FileReader.readAsDataURL() 将图片转为 Base64，无需网络请求即可显示。

4. 上传图片到 Coze：获取 file_id

const uploadFile = async () => {
  const formData = new FormData()
  const input = uploadImage.value
  if (!input.files || input.files.length <= 0) return

  formData.append('file', input.files[0])

  const res = await fetch(uploadUrl, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${patToken}`
    },
    body: formData
  })

  const ret = await res.json()
  console.log(ret)
  if (ret.code !== 0) {
    status.value = ret.msg
    return
    // 当code为0时 表示没有错误 那么这里进行判断 当不为0时 返回错误信息给status.value
  }

  return ret.data.id // 关键：返回 file_id 供后续工作流使用
}

⚠️ 常见错误排查：

  • 若返回 {"code":700012006,"msg":"cannot get access token from Authorization header"}，说明 patToken 未正确设置或格式错误；
  • 确保请求头为 'Authorization': 'Bearer xxx'，注意大小写和空格。

5. 调用 Coze 工作流：生成 AI 图像

const generate = async () => {
  status.value = '图片上传中...'
  const file_id = await uploadFile()
  if (!file_id) return

  status.value = '图片上传成功，正在生成中...'

  const parameters = {
    picture: JSON.stringify({ file_id }), // 注意：需 stringify
    style: style.value,
    uniform_color: uniform_color.value,
    uniform_number: uniform_number.value,
    position: position.value,
    shooting_hand: shooting_hand.value
  }

  const res = await fetch(workflowUrl, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${patToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id,
      parameters
    })
  })

  const ret = await res.json()
  if (ret.code !== 0) {
    status.value = ret.msg
    return
  }

  const data = JSON.parse(ret.data) // 注意：Coze 返回的是字符串化的 JSON
  imgUrl.value = data.data
  status.value = ''
}

❗ 重要细节：

  • picture 字段必须是 JSON.stringify({ file_id })，因为 Coze 工作流节点可能期望字符串输入；
  • ret.data 是字符串，需再次 JSON.parse 才能得到真正的结果对象；
  • 若遇到 {"code":4000,"msg":"The requested API endpoint GET /v1/workflow/run does not exist..."}，说明你用了 GET 方法，但该接口只支持 POST！

四、样式与布局（Scoped CSS）

<style scoped>
.container {
  display: flex;
  flex-direction: row;
  height: 100vh;
}

.input {
  display: flex;
  flex-direction: column;
  min-width: 330px;
}

.generated {
  width: 400px;
  height: 400px;
  border: solid 1px black;
  display: flex;
  justify-content: center;
  align-items: center;
}
</style>

✨ 使用 scoped 确保样式隔离，避免污染全局；弹性布局实现左右两栏（配置区 + 结果区）。

五、总结与延伸

本项目完整展示了如何将 前端交互 与 AI 工作流 结合：

  • 利用 Vue3 的响应式系统管理状态；
  • 通过 FileReader 实现即时预览；
  • 使用 fetch + FormData 安全上传文件；
  • 调用 Coze API 实现“上传 → 生成 → 展示”闭环。

最后提醒：

  • 务必保护好你的 PAT Token；
  • 遵守 Coze 的 API 调用频率限制，如果无法响应，可以尝试更换你的Coze API；
  • 测试不同风格下的生成效果，优化用户体验。

通过这个小而美的项目，你不仅能掌握 Vue3 的实战技巧，还能深入理解如何将 AI 能力无缝集成到 Web 应用中。快去试试吧，让你的宠物穿上冰球队服，成为下一个 AI 冰球明星！🏒🐶

❌
❌