CSS 也要支持 if 了 ！！！CSS if() 函数来了！

CSS if() 函数允许在纯 CSS 中基于条件为属性赋值，无需 JavaScript 或预处理器。该函数已在 Chrome 137 发布。

过去常用的做法包括通过 JavaScript 切换类名、使用预处理器 mixin 或编写大量媒体查询。if() 将条件逻辑引入 CSS，使写法更直接、性能稳定。

原文 CSS 也要支持 if 了 ！！！CSS if() 函数来了！

工作原理

property: if(condition-1: value-1; condition-2: value-2; condition-3: value-3; else: default-value);

函数按顺序检查条件并应用第一个匹配的值；若没有条件匹配，则使用 else 的值。这一语义与常见编程语言一致，但实现于纯 CSS。

if() 的三种能力

样式查询（Style queries）

使用 style() 可响应 CSS 自定义属性：

.card {

  --status: attr(data-status type(<custom-ident>));



  border-color: if(style(--status: pending): royalblue; style(--status: complete): seagreen; style(--status: error): crimson; else: gray);

}

一个 data-status 属性即可驱动对应样式，无需额外工具类。

媒体查询（Media queries）

使用 media() 可以在属性内联定义响应式值，无需嵌套媒体查询块：

h1 {

  font-size: if(media(width >= 1200px): 3rem; media(width >= 768px): 2.5rem; media(width >= 480px): 2rem; else: 1.75rem);

}

特性检测（Feature detection）

使用 supports() 可在属性中直接进行特性检测，并提供明确回退：

.element {

  border-color: if(supports(color: lch(0 0 0)): lch(50% 100 150) ; supports(color: lab(0 0 0)): lab(50 100 -50) ; else: rgb(200, 100, 50));

}

真实用例

暗色模式示例

body {

  --theme: 'dark'; /* 通过 JavaScript 或用户偏好切换 */



  background: if(style(--theme: 'dark'): #1a1a1a; else: white);



  color: if(style(--theme: 'dark'): #e4e4e4; else: #333);

}

设计系统状态组件

.alert {

  --type: attr(data-type type(<custom-ident>));



  background: if(style(--type: success): #d4edda; style(--type: warning): #fff3cd; style(--type: danger): #f8d7da; style(--type: info): #d1ecf1; else: #f8f9fa);



  border-left: 4px solid if(style(--type: success): #28a745; style(--type: warning): #ffc107; style(--type: danger): #dc3545; style(--type: info): #17a2b8; else: #6c757d);

}

容器尺寸示例（简化媒体查询）

.container {

  width: if(media(width >= 1400px): 1320px; media(width >= 1200px): 1140px; media(width >= 992px): 960px; media(width >= 768px): 720px; media(width >= 576px): 540px; else: 100%);



  padding-inline: if(media(width >= 768px): 2rem; else: 1rem);

}

与现代 CSS 特性结合

.element {

  /* 搭配新的 light-dark() 函数 */

  color: if(style(--high-contrast: true): black; else: light-dark(#333, #e4e4e4));



  /* 搭配 CSS 自定义函数（@function） */

  padding: if(style(--spacing: loose): --spacing-function(2) ; style(--spacing: tight): --spacing-function(0.5) ; else: --spacing-function(1));

}

浏览器支持

支持情况（截至 2025 年 8 月）：

• ✅ Chrome/Edge：自 137 版起


• ✅ Chrome Android：自 139 版起


• ❌ Firefox：开发中


• ❌ Safari：在规划中


• ❌ Opera：尚未支持

在尚未完全支持的环境中，可采用如下写法：

.button {

  /* 所有浏览器的回退 */

  padding: 1rem 2rem;

  background: #007bff;



  /* 现代浏览器会自动覆盖 */

  padding: if(style(--size: small): 0.5rem 1rem; style(--size: large): 1.5rem 3rem; else: 1rem 2rem);



  background: if(style(--variant: primary): #007bff; style(--variant: success): #28a745; style(--variant: danger): #dc3545; else: #6c757d);

}

未来展望

CSS 工作组已经在推进扩展能力：

• 范围查询：if(style(--value > 100): ...)


• 逻辑运算符：if(style(--a: true) and style(--b: false): ...)


• 容器查询集成：更强的上下文感知

在使用前建议评估目标浏览器版本，并准备相应回退方案。

实战推荐：

• 不仅免费，还开源？这个 AI Mock 神器我必须曝光它


• ⚡ 一个Vue自定义指令搞定丝滑拖拽列表，告别复杂组件封装
  


• 🔥 这才是 Vue 驱动的 Chrome 插件工程化正确打开方式


• 女朋友又给我出难题了：解锁网页禁用复制 + 一键提取图片文字

还在为每个列表页写重复的分页代码而烦恼吗？ 还在复制粘贴 currentPage、pageSize、loading 等状态吗？ 一个 Hook 帮你解决所有分页痛点，减少90%重复代码

背景与痛点

在后台管理系统开发中，分页列表查询非常常见，我们通常需要处理：

• 当前页、页大小、总数等分页状态


• 加载中、错误处理等请求状态


• 搜索、刷新、翻页等分页操作


• 数据缓存和重复请求处理

这些重复逻辑分散在各个组件中，维护起来很麻烦。

为了解决这个烦恼，我专门封装了分页数据管理 Hook。现在只需要几行代码，就能轻松实现分页查询，省时又高效，减少了大量重复劳动

使用前提 - 接口格式约定

查询接口返回的数据格式：

{

  list: [        // 当前页数据数组

    { id: 1, name: 'user1' },

    { id: 2, name: 'user2' }

  ],

  total: 100     // 数据总条数

}

先看效果：分页查询只需几行代码！

import usePageFetch from '@/hooks/usePageFetch' // 引入分页查询 Hook，封装了分页逻辑和状态管理

import { getUserList } from '@/api/user'        // 引入请求用户列表的 API 方法



// 使用 usePageFetch Hook 实现分页数据管理

const {

  currentPage,      // 当前页码

  pageSize,         // 每页条数

  total,            // 数据总数

  data,             // 当前页数据列表

  isFetching,       // 加载状态，用于控制 loading 效果

  search,           // 搜索方法

  onSizeChange,     // 页大小改变事件处理方法

  onCurrentChange   // 页码改变事件处理方法

} = usePageFetch(

  getUserList,  // 查询API

  { initFetch: false }  // 是否自动请求一次（组件挂载时自动拉取第一页数据）     

)

这样子每次分页查询只需要引入hook，然后传入查询接口就好了，减少了大量重复劳动

解决方案

我设计了两个相互配合的 Hook：

• useFetch：基础请求封装，处理请求状态和缓存


• usePageFetch：分页逻辑封装，专门处理分页相关的状态和操作

usePageFetch (分页业务层)

├── 管理 page / pageSize / total 状态

├── 处理搜索、刷新、翻页逻辑  

├── 统一错误处理和用户提示

└── 调用 useFetch (请求基础层)

    ├── 管理 loading / data / error 状态

    ├── 可选缓存机制（避免重复请求）

    └── 成功回调适配不同接口格式

核心实现

useFetch - 基础请求封装

// hooks/useFetch.js

import { ref } from 'vue'



const Cache = new Map()



/**

 * 基础请求 Hook

 * @param {Function} fn - 请求函数

 * @param {Object} options - 配置选项

 * @param {*} options.initValue - 初始值

 * @param {string|Function} options.cache - 缓存配置

 * @param {Function} options.onSuccess - 成功回调

 */

function useFetch(fn, options = {}) {

  const isFetching = ref(false)

  const data = ref()

  const error = ref()



  // 设置初始值

  if (options.initValue !== undefined) {

    data.value = options.initValue

  }



  function fetch(...args) {

    isFetching.value = true

    let promise



    if (options.cache) {

      const cacheKey = typeof options.cache === 'function'

        ? options.cache(...args)

        : options.cache || `${fn.name}_${args.join('_')}`



      promise = Cache.get(cacheKey) || fn(...args)

      Cache.set(cacheKey, promise)

    } else {

      promise = fn(...args)

    }



    // 成功回调处理

    if (options.onSuccess) {

      promise = promise.then(options.onSuccess)

    }



    return promise

      .then(res => {

        data.value = res

        isFetching.value = false

        error.value = undefined

        return res

      })

      .catch(err => {

        isFetching.value = false

        error.value = err

        return Promise.reject(err)

      })

  }



  return {

    fetch,

    isFetching,

    data,

    error

  }

}



export default useFetch

usePageFetch - 分页逻辑封装

// hooks/usePageFetch.js

import { ref, onMounted, toRaw, watch } from 'vue'

import useFetch from './useFetch' // 即上面的hook ---> useFetch 

import { ElMessage } from 'element-plus'



/**

 * 分页数据管理 Hook

 * @param {Function} fn - 请求函数

 * @param {Object} options - 配置选项

 * @param {Object} options.params - 默认参数

 * @param {boolean} options.initFetch - 是否自动初始化请求

 * @param {Ref} options.formRef - 表单引用

 */

function usePageFetch(fn, options = {}) {

  // 分页状态

  const page = ref(1)

  const pageSize = ref(10)

  const total = ref(0)

  const data = ref([])

  const params = ref()

  const pendingCount = ref(0)



  // 初始化参数

  params.value = options.params



  //  使用基础请求 Hook

  const { isFetching, fetch: fetchFn, error, data: originalData } = useFetch(fn)



  //  核心请求方法

  const fetch = async (searchParams, pageNo, size) => {

    try {

      // 更新分页状态

      page.value = pageNo

      pageSize.value = size

      params.value = searchParams



      // 发起请求

      await fetchFn({

        page: pageNo,

        pageSize: size,

        // 使用 toRaw 避免响应式对象问题

        ...(searchParams ? toRaw(searchParams) : {})

      })



      // 处理响应数据

      data.value = originalData.value?.list || []

      total.value = originalData.value?.total || 0

      pendingCount.value = originalData.value?.pendingCounts || 0

    } catch (e) {

      console.error('usePageFetch error:', e)

      ElMessage.error(e?.msg || e?.message || '请求出错')

      // 清空数据，提供更好的用户体验

      data.value = []

      total.value = 0

    }

  }



  //  搜索 - 重置到第一页

  const search = async (searchParams) => {

    await fetch(searchParams, 1, pageSize.value)

  }



  // 刷新当前页

  const refresh = async () => {

    await fetch(params.value, page.value, pageSize.value)

  }



  // 改变页大小

  const onSizeChange = async (size) => {

    await fetch(params.value, 1, size) // 重置到第一页

  }



  // 切换页码

  const onCurrentChange = async (pageNo) => {

    await fetch(params.value, pageNo, pageSize.value)

  }



  // 组件挂载时自动请求

  onMounted(() => {

    if (options.initFetch !== false) {

      search(params.value)

    }

  })



  // 监听表单引用变化（可选功能）

  watch(

    () => options.formRef,

    (formRef) => {

      if (formRef) {

        console.log('Form ref updated:', formRef)

      }

    }

  )



  return {

    // 分页状态

    currentPage: page,

    pageSize,

    total,

    pendingCount,

    

    // 数据状态

    data,

    originalData,

    isFetching,

    error,

    

    // 操作方法

    search,

    refresh,

    onSizeChange,

    onCurrentChange

  }

}



export default usePageFetch

完整使用示例

用element ui举例

<template>

    <el-form :model="searchForm" >

      <el-form-item label="用户名">

        <el-input v-model="searchForm.username" />

      </el-form-item>

      <el-form-item>

        <el-button type="primary" @click="handleSearch">搜索</el-button>

      </el-form-item>

    </el-form>

  <!-- 表格数据展示，绑定 data 和 loading 状态 -->

  <el-table :data="data" v-loading="isFetching">

    <!-- ...表格列定义... -->

  </el-table>



  <!-- 分页组件，绑定当前页、页大小、总数，并响应切换事件 -->

  <el-pagination

    v-model:current-page="currentPage"

    v-model:page-size="pageSize"

    :total="total"

    @size-change="onSizeChange"

    @current-change="onCurrentChange"

  />

</template>

<script setup>

import { ref } from 'vue'

import usePageFetch from '@/hooks/usePageFetch' // 引入分页查询 Hook，封装了分页逻辑和状态管理

import { getUserList } from '@/api/user'        // 引入请求用户列表的 API 方法



// 搜索表单数据，响应式声明

const searchForm = ref({

  username: ''

})



// 使用 usePageFetch Hook 实现分页数据管理

const {

  currentPage,      // 当前页码

  pageSize,         // 每页条数

  total,            // 数据总数

  data,             // 当前页数据列表

  isFetching,       // 加载状态，用于控制 loading 效果

  search,           // 搜索方法

  onSizeChange,     // 页大小改变事件处理方法

  onCurrentChange   // 页码改变事件处理方法

} = usePageFetch(

  getUserList, 

  { initFetch: false }  // 是否自动请求一次（组件挂载时自动拉取第一页数据）     

)



/**

* 处理搜索操作

*/

const handleSearch = () => {

  search({ username: searchForm.value.username })

}



</script>

高级用法

带缓存

const {

  data,

  isFetching,

  search

} = usePageFetch(getUserList, {

  cache: (params) => `user-list-${JSON.stringify(params)}` // 自定义缓存 key

})

设计思路解析

• 职责分离：useFetch 专注请求状态管理，usePageFetch 专注分页逻辑


• 统一错误处理：在 usePageFetch 层统一处理错误


• 智能缓存机制：支持多种缓存策略


• 生命周期集成：自动在组件挂载时请求数据

总结

这套分页管理 Hook 的优势：

• 开发效率高，减少90%的重复代码，新增列表页从 30 分钟缩短到 5 分钟


• 状态管理完善，自动处理加载、错误、数据状态


• 缓存机制，避免重复请求


• 错误处理统一，用户体验一致


• 易于扩展，支持自定义配置和回调

如果觉得对您有帮助，欢迎点赞 👍 收藏 ⭐ 关注 🔔 支持一下！

vue-router悄悄发布了5.0版本，用官方的话说，V5 是一个过渡版本，它将unplugin-vue-router（基于文件的路由）合并到了核心包中，就是说V5版本直接支持基于文件自动生成路由了，无需再引入unplugin-vue-router。

这一变化标志着前端开发模式的一个重要转折点。过去，开发者需要手动定义路由配置，这种方式虽然灵活，但随着项目规模增大，维护成本也随之增加。现在，Vue Router 5.0内置了基于文件的路由系统，使得路由管理变得更加直观和高效。

传统路由配置与基于文件路由的对比

在传统的Vue Router使用方式中，我们需要手动创建路由：

import { createRouter, createWebHistory } from "vue-router";

import Home from "./views/Home.vue";

import About from "./views/About.vue";



const routes = [

  {

    path: "/",

    name: "home",

    component: Home,

  },

  {

    path: "/about",

    name: "about",

    component: About,

  },

];



const router = createRouter({

  history: createWebHistory(),

  routes,

});

而基于文件的路由系统允许我们通过目录结构自动生成路由，例如：

src/

├── pages/

│   ├── index.vue        # -> /

│   ├── about.vue        # -> /about

│   ├── user/

│   │   └── index.vue    # -> /user

│   └── user-[id].vue    # -> /user/:id

无需手动创建，直接导入即可：

import { routes } from "vue-router/auto-routes";



const router = createRouter({

  history: createWebHistory(),

  routes,

});

省去了手动定义路由的繁琐步骤。

基于文件路由的优势

缺点

快速入门

安装

pnpm add vue-router@5

vite.config.ts

import VueRouter from "vue-router/vite";



export default defineConfig({

  plugins: [

    VueRouter({

      dts: "typed-router.d.ts",

    }),

    // ⚠️ Vue must be placed after VueRouter()

    Vue(),

  ],

});

tsconfig.json

// tsconfig.json

{

  "include": [ "typed-router.d.ts" ],

  "vueCompilerOptions": {

    "plugins": [

      "vue-router/volar/sfc-typed-router",

      "vue-router/volar/sfc-route-blocks"

    ]

  }

}

src/router/index.ts

import { createRouter, createWebHistory } from "vue-router";

import { routes, handleHotUpdate } from "vue-router/auto-routes";



export const router = createRouter({

  history: createWebHistory(),

  routes,

});



// This will update routes at runtime without reloading the page

if (import.meta.hot) {

  handleHotUpdate(router);

}

详细的路由生成规则

根据官方文档，基于文件的路由系统有以下具体规则：

索引路由：任何 index.vue 文件（必须全小写）将生成空路径，类似于 index.html 文件：

• src/pages/index.vue 生成 / 路由


• src/pages/users/index.vue 生成 /users 路由

嵌套路由：当在同一层级同时存在同名文件夹和 .vue 文件时，会自动生成嵌套路由。例如：

src/pages/

├── users/

│   └── index.vue

└── users.vue

这将生成如下路由配置：

const routes = [

  {

    path: "/users",

    component: () => import("src/pages/users.vue"),

    children: [

      { path: "", component: () => import("src/pages/users/index.vue") },

    ],

  },

];

不带布局嵌套的路由：有时候你可能想在URL中添加斜杠形式的嵌套，但不想影响UI层次结构。可以使用点号(.)分隔符：

src/pages/

├── users/

│   ├── [id].vue

│   └── index.vue

└── users.vue

要添加 /users/create 路由而不将其嵌套在 users.vue 组件内，可以创建 src/pages/users.create.vue 文件，. 会被转换为 /：

const routes = [

  {

    path: "/users",

    component: () => import("src/pages/users.vue"),

    children: [

      { path: "", component: () => import("src/pages/users/index.vue") },

      { path: ":id", component: () => import("src/pages/users/[id].vue") },

    ],

  },

  {

    path: "/users/create",

    component: () => import("src/pages/users.create.vue"),

  },

];

路由组：有时候需要组织文件结构而不改变URL。路由组允许你逻辑性地组织路由，不影响实际URL：

src/pages/

├── (admin)/

│   ├── dashboard.vue

│   └── settings.vue

└── (user)/

    ├── profile.vue

    └── order.vue

生成的URL：

• /dashboard -> 渲染 src/pages/(admin)/dashboard.vue


• /settings -> 渲染 src/pages/(admin)/settings.vue


• /profile -> 渲染 src/pages/(user)/profile.vue


• /order -> 渲染 src/pages/(user)/order.vue

命名视图：可以通过在文件名后附加 @ + 名称来定义命名视图，如 src/pages/index@aux.vue 将生成：

{

  path: '/',

  component: {

    aux: () => import('src/pages/index@aux.vue')

  }

}

默认情况下，未命名的路由被视为 default，即使有其他命名视图也不需要将文件命名为 index@default.vue。

动态路由：使用方括号语法定义动态参数：

• [id].vue -> /users/:id


• [category]-details.vue -> /electronics-details


• [...all].vue -> 通配符路由 /all/*

对开发工作流的影响

这一变化将显著改变Vue应用的开发流程：

• 新功能页面的添加变得更加简单


• 团队成员更容易理解项目的路由结构


• 减少了因手动配置错误导致的路由问题


• 更好的IDE集成和自动补全支持

迁移策略

对于现有项目，Vue Router 5.0提供了平滑的迁移路径：

• 旧的路由配置方式依然有效


• 可以逐步采用基于文件的路由


• 混合使用两种方式以适应不同场景

配置选项和高级功能

Vue Router 5.0的基于文件路由系统提供了丰富的配置选项，可以根据项目需求进行定制：

自定义路由目录：默认情况下，系统会在 src/pages 目录中查找 .vue 文件，但可以通过配置更改此行为。

命名路由：所有生成的路由都会自动获得名称属性，避免意外将用户引导至父路由。默认情况下，名称使用文件路径生成，但可以通过自定义 getRouteName() 函数覆盖此行为。

类型安全：系统会自动生成类型声明文件（如 typed-router.d.ts），提供几乎无处不在的 TypeScript 验证。

配置示例：

// vite.config.js

import { defineConfig } from "vite";

import vue from "@vitejs/plugin-vue";

import VueRouter from "unplugin-vue-router/vite";



export default defineConfig({

  plugins: [

    VueRouter({

      routesFolder: "src/pages", // 自定义路由目录

      extensions: [".vue"], // 指定路由文件扩展名

      dts: "typed-router.d.ts", // 生成类型声明文件

      importMode: (filename) => "async", // 自定义导入模式

    }),

    vue(),

  ],

});

实际应用建议

在实际项目中采用基于文件的路由时，建议遵循以下最佳实践：

总结

Vue Router 5.0引入的基于文件的路由系统代表了前端开发模式的重要演进。它将 Nuxt.js 等框架成功的路由理念整合到了 Vue 的核心生态中，使开发者能够以更简洁、更直观的方式管理应用路由。

这一变化不仅减少了样板代码，提高了开发效率，还促进了更一致的项目结构。随着更多开发者采用这一新模式，我们可以期待看到更高质量、更易维护的 Vue 应用程序出现，这将为整个前端社区带来积极的影响。

在企业级应用开发中，权限控制是一个绑不开的话题。前端权限控制虽然不能替代后端校验，但能极大提升用户体验——让用户只看到自己能操作的内容，避免无效点击和困惑。

本文将分享一个 Vue 2 自定义指令的设计思路，实现了声明式的权限控制方案。

设计目标

在动手写代码之前，我先梳理了几个核心诉求：

核心实现

1. 权限缓存设计

权限校验通常需要请求后端接口，如果每个按钮都单独请求一次，那页面性能会非常糟糕。这里采用了 Promise 缓存 的方式：

Vue.prototype.$getPerm = (options) => {

    const argId = options.type + '-' + (options.type === 'space' ? options.spaceId : options.wikiId)

    

    // 如果缓存中没有，创建新的 Promise

    if (!spaceInfoStore.permissionMap[argId]) {

        spaceInfoStore.permissionMap[argId] = new Promise((resolve, reject) => {

            // 请求后端获取权限...

            Auth.getUserPermBySpaceId(options.spaceId).then((res) => {

                const permissions = res.reduce((acc, category) => {

                    category.permissions.forEach(permission => {

                        acc.push(`${category.value}.${permission.authorityKey}`)

                    })

                    return acc

                }, [])

                resolve({ permissions })

            })

        })

    }

    return spaceInfoStore.permissionMap[argId]

}

这个设计的巧妙之处在于：缓存的是 Promise 本身，而不是结果。

这样做的好处是，即使多个组件同时调用 $getPerm，也只会发出一次请求。后续的调用会直接拿到同一个 Promise，等待第一次请求的结果。

2. 双重使用方式

为了覆盖不同的使用场景，我设计了两种调用方式：

方式一：指令式（模板中使用）

<button v-perm:[permOptions]="'SPACE.EDIT'">编辑</button>

方式二：编程式（JS 中使用）

this.$hasPerm({ spaceId: 123 }, 'SPACE.EDIT').then(() => {

    // 有权限，执行操作

}).catch(() => {

    // 无权限

})

指令式适合静态权限控制，编程式适合需要在逻辑中判断的场景。两者底层共用同一套缓存机制。

3. DOM 处理策略

无权限时如何处理 DOM？这里提供了三种策略：

function domHandler (el, binding) {

    let placeholderDom = null

    

    if (binding?.arg?.showTips || binding?.arg?.disabled) {

        // 策略1&2：保留元素，但禁用或添加点击提示

        placeholderDom = el.cloneNode(true)

        

        if (binding?.arg?.showTips) {

            placeholderDom.onclick = function () {

                Vue.prototype.$bkMessage({

                    message: binding?.arg?.tipsText || '没有权限',

                    theme: 'warning'

                })

            }

        }

        

        if (binding?.arg?.disabled) {

            placeholderDom.classList.add('disabled')

        }

    } else {

        // 策略3：完全隐藏，用注释节点占位

        placeholderDom = document.createComment('permission-placeholder')

    }

    

    el.placeholderDom = placeholderDom

    el.parentNode.replaceChild(placeholderDom, el)

}

为什么用注释节点而不是直接 display: none？

因为注释节点不会影响布局，也不会被 CSS 选择器选中。更重要的是，我们需要保留一个"锚点"，方便权限变化时把原始元素恢复回去。

4. 响应式更新

权限可能会动态变化（比如用户被授权后刷新），所以指令需要同时监听 inserted 和 update 钩子：

Vue.directive('perm', {

    inserted (el, binding) {

        handlerPerm(el, binding)

    },

    update (el, binding) {

        handlerPerm(el, binding)

    }

})

恢复元素的逻辑也很简单：

function restoreElement (el) {

    if (el.placeholderDom && el.placeholderDom.parentNode) {

        el.placeholderDom.parentNode.replaceChild(el, el.placeholderDom)

    }

    el.placeholderDom = null

    return true

}

5. 支持布尔值快捷方式

有时候权限结果已经在外部计算好了，不需要再走一遍接口校验。这种场景下，支持直接传布尔值会更方便：

<button v-perm:[options]="hasPermission">操作</button>

if (typeof binding.value === 'boolean') {

    if (binding.value === false) {

        domHandler(el, binding)

    } else {

        restoreElement(el)

    }

    return

}

使用示例

基础用法

<template>

    <div>

        <!-- 无权限时隐藏 -->

        <button v-perm:[permConfig]="'SPACE.DELETE'">删除</button>

        

        <!-- 无权限时禁用并提示 -->

        <button v-perm:[permConfigWithTips]="'SPACE.EDIT'">编辑</button>

    </div>

</template>



<script>

export default {

    computed: {

        permConfig() {

            return {

                spaceId: this.currentSpaceId,

                type: 'space'

            }

        },

        permConfigWithTips() {

            return {

                spaceId: this.currentSpaceId,

                type: 'space',

                disabled: true,

                showTips: true,

                tipsText: '您没有编辑权限，请联系管理员'

            }

        }

    }

}

</script>

编程式调用

// 在执行敏感操作前校验

async handleDelete() {

    try {

        await this.$hasPerm({ spaceId: this.spaceId }, 'SPACE.DELETE')

        // 有权限，继续执行删除逻辑

        await this.doDelete()

    } catch {

        // 无权限，$hasPerm 内部已经弹出提示

    }

}

清除缓存重新加载

当权限发生变化时（比如管理员授权后），可以清除缓存重新加载：

this.$getPerm({ 

    spaceId: this.spaceId, 

    clearCache: true 

})

设计总结

可以优化的点

以上就是这个权限指令的完整设计思路。核心思想是：用缓存换性能，用指令换简洁。希望对你有所启发，欢迎交流讨论 🙌

完整代码

最后贴一下完整代码，可以直接拿去用，根据自己项目的接口改一下就行：

// permission.js

import { useSpaceInfoStore } from '@/store/modules/spaceInfo'

import Auth from '@/api/modules/auth'



let spaceInfoStore = null

setTimeout(() => {

    spaceInfoStore = useSpaceInfoStore()

}, 40)



/**

 * @typedef {Object} PermissionOptions

 * @property {string|number} [wikiId] - 文档id

 * @property {string|number} [spaceId] - 空间id

 * @property {string} [type] - 权限类型：空间/文档   space/wiki

 * @property {boolean} [disabled] - 是否禁用元素

 * @property {boolean} [showTips] - 是否显示提示信息

 * @property {string} [tipsText] - 提示文本内容

 * @property {boolean} [clearCache] - 是否清除缓存

 */



function install (Vue) {

    /**

     * 获取权限信息

     * @param {PermissionOptions} options - 权限选项

     * @returns {Promise<any>}

     */

    Vue.prototype.$getPerm = (options) => {

        if (!options.spaceId) return

        // 如果没有传type，则根据是否有文档id判断

        options.type = options.type || (options.wikiId ? 'wiki' : 'space')

        const argId = options.type + '-' + (options.type === 'space' ? options.spaceId : options.wikiId)

        // 清除缓存权限，可重新加载

        if (options.clearCache) {

            spaceInfoStore.permissionMap[argId] = false

        }

        if (!spaceInfoStore.permissionMap[argId]) {

            spaceInfoStore.permissionMap[argId] = new Promise((resolve, reject) => {

                if (options.type === 'space') {

                    Auth.getUserPermBySpaceId(options.spaceId).then((res) => {

                        // 组合权限生成唯一key

                        const permissions = res.reduce((acc, category) => {

                            category.permissions.forEach(permission => {

                                acc.push(`${category.value}.${permission.authorityKey}`)

                            })

                            return acc

                        }, [])

                        resolve({ permissions })

                    })

                } else {

                    Auth.getWikiPermissionDetail(options.spaceId, options.wikiId).then((res) => {

                        // 组合权限生成唯一key

                        const permissions = res.map(item => item.authorityKey)

                        resolve({ permissions })

                    })

                }

            })

        }

        return spaceInfoStore.permissionMap[argId]

    }



    /**

     * 检查是否有权限

     * @param {PermissionOptions} options - 权限选项

     * @param {string} perm - 权限码

     * @returns {Promise<boolean>}

     */

    Vue.prototype.$hasPerm = (options, perm) => {

        if (!Object.prototype.hasOwnProperty.call(options, 'showTips')) {

            options.showTips = true

        }

        return new Promise((resolve, reject) => {

            if (!options.spaceId) {

                resolve(true)

                return

            }

            const promise = Vue.prototype.$getPerm(options)

            promise.then((res) => {

                if (res.isAdmin) {

                    resolve(true)

                    return

                }

                if (res.permissions.includes(perm)) {

                    resolve(true)

                    return

                }

                if (options.showTips) {

                    Vue.prototype.$bkMessage({

                        message: options.tipsText || '没有权限',

                        theme: 'warning'

                    })

                }

                reject(new Error(''))

            })

        })

    }



    /**

     * DOM 处理函数 - 处理无权限时的元素显示

     * @param {HTMLElement} el - DOM 元素

     * @param {Object} binding - 指令绑定对象

     */

    function domHandler (el, binding) {

        let placeholderDom = null

        if (binding?.arg?.showTips || binding?.arg?.disabled) {

            placeholderDom = el.cloneNode(true)

            if (binding?.arg?.showTips) {

                placeholderDom.onclick = function () {

                    Vue.prototype.$bkMessage({

                        message: binding?.arg?.tipsText || '没有权限',

                        theme: 'warning'

                    })

                }

            }

            if (binding?.arg?.disabled) {

                placeholderDom.classList.add('disabled')

            }

        } else {

            placeholderDom = document.createComment('permission-placeholder')

        }

        if (el.parentNode) {

            el.placeholderDom = placeholderDom

            el.parentNode.replaceChild(placeholderDom, el)

        }

    }



    /**

     * 将元素恢复到原始位置

     * @param {HTMLElement} el - DOM 元素

     * @returns {boolean}

     */

    function restoreElement (el) {

        el.placeholderDom && el.placeholderDom.parentNode.replaceChild(el, el.placeholderDom)

        el.placeholderDom = null

        return true

    }



    /**

     * 权限处理函数

     * @param {HTMLElement} el - DOM 元素

     * @param {Object} binding - 指令绑定对象

     */

    function handlerPerm (el, binding) {

        // 通过直接传递boolean值，也可以进行权限校验

        if (typeof binding.value === 'boolean') {

            if (binding.value === false) {

                domHandler(el, binding)

            } else {

                restoreElement(el)

            }

            return

        }

        // 判断权限入参是否完善

        if (!binding?.arg?.spaceId || !binding?.value) return restoreElement(el)

        const promise = Vue.prototype.$getPerm({ ...binding.arg })

        promise.then((res) => {

            if (res.isAdmin) return restoreElement(el)

            if (res.permissions.includes(binding.value)) return restoreElement(el)

            domHandler(el, binding)

        })

    }



    Vue.directive('perm', {

        inserted (el, binding) {

            handlerPerm(el, binding)

        },

        update (el, binding) {

            handlerPerm(el, binding)

        }

    })

}



export default { install }

在 main.js 里注册一下就能用了：

import permission from '@/directives/permission'

Vue.use(permission)

业务背景

在正式讲之前，先看一个我们做的大文件上传demo。
下面这个视频演示的是上传一个 1GB 的压缩包，整个过程支持分片上传、断点续传、暂停和恢复。

可以看到速度不是特别快，这个是我故意没去优化的。
前端那边计算文件 MD5、以及最后合并文件的时间我都保留了，
主要是想让大家能看到整个流程是怎么跑通的。

平时我们在做一些 SaaS 系统的时候，文件上传这块其实基本上都设计的挺简单的。
前端做个分片上传，后端把分片合并起来，最后存 OSS 或者服务器某个路径上，再返回一个 URL 就完事了。
大多数情况下，这样的方案也确实够用。

但是最近我在做一个私有化项目，场景完全不一样。
项目是给政企客户部署的内部系统，里面有 AI 大模型客服问答的功能。
客户需要把他们内部的文档、手册、规范、图纸、流程等资料打包上传到服务器，用来做后续的向量化、知识检索或者模型训练。

这类场景如果还沿用之前 SaaS 系统那种上传方式，往往就不太适用了。
因为这些文件往往有几个共同点：

0. 文件数量多，动辄几百上千份（Word、PDF、PPT、Markdown 都有）；
1. 文件体积大，打成 zip 动不动就是几个 G，甚至十几二十个 G；
2. 上传环境复杂，客户一般在内网或局域网，有的甚至完全断网；
3. 有安全要求，文件不能经过云端 OSS，里面可能有保密资料；
4. 需要审计，要能知道是谁上传的、什么时候传的、文件现在存哪；
5. 上传完之后还要进一步处理，比如自动解压、解析文本、拆页、向量化，然后再存入 Milvus 或 pgvector。

所以这种情况还用 SaaS 系统那种“简单上传+云存储”方案的话，那可能问题就一堆：

• 上传中断后用户一刷新浏览器就得重传整个包；
• 集群部署时分片打到不同机器上根本无法合并；
• 多人同时上传可能会发生文件覆盖或路径冲突；
• 没有任何上传记录，也追踪不到是谁传的；
• 对政企来说，审计、合规、保密全都不达标。

所以，我们需要重新设计文件上传的功能逻辑。
目的是让它不仅能支持大文件、断点续传、集群部署，还能同时适配内网环境、权限管控，以及后续的 AI 文档解析和知识向量化等处理流程。

---

为什么很多项目只需要一个 upload 接口

如果我们回头看一下自己平常做过的一些常规 Web 项目，尤其是各种 SaaS 系统或者后台管理系统，
其实大多数时候后端只会提供一个 /upload 接口， 前端拿到文件后直接调用这个接口，后端保存文件再返回一个 URL 就结束了。

甚至我们在很多项目里，前端都不会把文件传给业务服务，
而是直接通过前端 SDK（比如阿里云 OSS、腾讯云 COS、七牛云等）上传到云存储，
上传完后拿到文件地址，再把这个地址回传给后端保存。

这种方式在 SaaS 系统或者轻量级的业务里非常普遍，也非常高效。 主要原因有几个：

1. 文件都比较小，大多数就是几 MB 的图片、PDF 或 Excel；
2. 云存储足够稳定，上传、下载、访问都有完整的 SDK 支撑；
3. 系统是公网部署，不需要考虑局域网、内网断网这些问题；
4. 对安全和审计的要求不高，文件内容也不是涉密数据；
5. 用户体验优先，所以直接把文件上传到云端是最省事的方案。

换句话说，这种“一个 upload 接口”或“前端直传 OSS”模式，其实是面向通用型 SaaS 场景的。
对于绝大多数互联网业务来说，它既够快又够省心。

但一旦项目换成政企、私有化部署或者 AI 训练平台这种环境，
就完全不是一个量级的问题了。
这里的关键不在“能不能上传”，
而在于文件上传之后的可控性、可追溯性和安全性。

---

前端常见的大文件上传方式

在重新设计后端接口之前，我们先来看看现在前端常见的大文件上传思路。
其实近几年前端这块已经比较成熟了，主流方案大体都是围绕几个核心点展开的：
秒传检测、分片上传、断点续传、并发控制、进度展示。

一般来说，前端拿到文件后，会先计算一个文件哈希值，比如用 MD5。
这样做的目的是为了做秒传检测：
如果服务器上已经存在这个文件，就可以直接跳过上传，节省时间和带宽。

接下来是分片上传。
文件太大时，前端会把文件拆成多个固定大小的小块（比如每块 5MB 或 10MB），
然后一片一片地上传。这样做可以避免一次性传输大文件导致浏览器卡顿或网络中断。

然后就是断点续传。
前端会记录哪些分片已经上传成功，如果上传过程中网络中断或浏览器刷新，
下次只需要从未完成的分片继续上传，不用重新传整包文件。

在性能方面，前端还会做并发控制。
比如同时上传三到五个分片，上传完一个就立刻补下一个，
这样整体速度比单线程串行上传要快很多。

最后是进度展示。
通过监听每个分片的上传状态，前端可以计算整体进度，
给用户展示一个实时的上传百分比或进度条，让体验更可控。

可以看到，前端的大文件上传方案已经形成了一套相对标准的模式。
所以这次我在重新设计后端的时候，就打算基于这种前端逻辑，
去构建一套更贴合企业私有化环境的上传接口控制体系。
目标是让前后端的职责划分更清晰：
前端负责切片、控制与恢复；后端负责存储、校验与合并。

---

后端接口设计思路

前端的大文件上传流程其实已经相对固定了，我们只要让后端的接口和它配合得上，就能把整个上传链路打通。
所以我这次重新设计时，把上传接口拆成了几个比较独立的阶段：
秒传检查、初始化任务、上传分片、合并文件、暂停任务、取消任务、任务列表。
每个接口都只负责一件事，这样接口的职责会更清晰，也方便后期扩展。

一、/upload/check —— 秒传检查

这个接口是整个流程的第一步，用来判断文件是否已经上传过。
前端在计算完文件的全局 MD5（或其他 hash）后，会先调这个接口。
如果后端发现数据库里已经有相同 hash 的文件，就直接返回“已存在”，前端就不用再上传了。

请求示例：

POST /api/upload/check

{

  "fileHash": "md5_abc123def456",

  "fileName": "training-docs.zip",

  "fileSize": 5342245120

}

返回示例：

{

  "success": true,

  "data": {

    "exists": false

  }

}

如果 exists = true，说明服务端已经有这个文件，可以直接走“秒传成功”的逻辑。

伪代码示例：

@PostMapping("/check")

public Result checkFile(@RequestBody Map body) {

    // 1. 校验 fileHash 参数是否为空

    // 2. 查询 file_info 表是否已有该文件

    // 3. 如果文件已存在，直接返回秒传成功（exists = true）

    // 4. 如果文件不存在，查询 upload_task 表中是否有未完成任务（支持断点续传）

}

二、/upload/init —— 初始化上传任务

如果文件不存在，就要先初始化一个新的上传任务。
这个接口的作用是创建一条 upload_task 记录，同时返回一个唯一的 uploadId。
前端会用这个 uploadId 来标识整个上传过程。

请求示例：

POST /api/upload/init

{

  "fileHash": "md5_abc123def456",

  "fileName": "training-docs.zip",

  "totalChunks": 320,

  "chunkSize": 5242880

}

返回示例：

{

  "success": true,

  "data": {

    "uploadId": "b4f8e3a7-1a0c-4a1d-88af-61e98d91a49b",

    "uploadedChunks": []

  }

}

uploadedChunks 用来支持断点续传，如果之前有部分分片上传过，就会在这里返回索引数组。

伪代码示例：

@PostMapping("/init")

public Result initUpload(@RequestBody UploadInitRequest request) {

    // 1. 检查是否已有同 fileHash 的任务，若有则返回旧任务信息（支持断点续传）

    // 2. 否则创建新的 upload_task 记录，生成 uploadId

    // 3. 初始化分片数量、大小、状态等信息

    // 4. 返回 uploadId 与已上传分片索引列表

}

三、/upload/chunk —— 上传单个分片

这是整个上传过程里调用次数最多的接口。
每个分片都会单独上传一次，并在服务端保存为临时文件，同时写入 upload_chunk 表。
上传成功后，后端会更新 upload_task 的进度信息。

请求示例（表单上传）：

POST /api/upload/chunk

Content-Type: multipart/form-data



formData:

  uploadId: b4f8e3a7-1a0c-4a1d-88af-61e98d91a49b

  chunkIndex: 0

  chunkSize: 5242880

  chunkHash: md5_001

  file: (二进制分片数据)

返回示例：

{

  "success": true,

  "data": {

    "uploadId": "b4f8e3a7-1a0c-4a1d-88af-61e98d91a49b",

    "chunkIndex": 0,

    "chunkSize": 5242880

  }

}

伪代码示例：

@PostMapping(value = "/chunk", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)

public Result uploadChunk(@ModelAttribute UploadChunkRequest req) {

    // 1. 校验任务状态，禁止上传已取消或已完成的任务

    // 2. 检查本地目录（或云端存储桶）是否存在，不存在则创建

    // 3. 接收当前分片文件并写入临时路径

    // 4. 写入 upload_chunk 表，标记状态为 “已上传”

    // 5. 更新 upload_task 的 uploaded_chunks 数量

}

四、/upload/merge —— 合并分片

当前端确认所有分片都上传完后，会调用 /upload/merge。
后端收到这个请求后，去检查所有分片是否完整，然后按照索引顺序依次合并。
合并成功后，会删除临时分片文件，并更新 upload_task 状态为“完成”。
如果启用了云存储，这一步也可以直接把合并后的文件上传到 OSS。

请求示例：

POST /api/upload/merge

{

  "uploadId": "b4f8e3a7-1a0c-4a1d-88af-61e98d91a49b",

  "fileHash": "md5_abc123def456"

}

返回示例：

{

  "success": true,

  "message": "文件合并成功",

  "data": {

    "storagePath": "/data/uploads/training-docs.zip"

  }

}

伪代码示例：

@PostMapping("/merge")

public Result mergeFile(@RequestBody UploadMergeRequest req) {

    // 1. 检查 upload_task 状态是否允许合并

    // 2. 校验所有分片是否都上传完成

    // 3. 如果是本地存储：按 chunk_index 顺序流式合并文件

    // 4. 如果是云存储：调用云端分片合并 API（如 OSS、COS）

    // 5. 校验文件 hash 完整性，更新任务状态为 COMPLETED

    // 6. 将最终文件信息写入 file_info 表

}

五、/upload/pause —— 暂停任务

这个接口用于在上传过程中手动暂停任务。
前端可能会在网络波动或用户主动点击暂停时调用。
后端会更新任务状态为“已暂停”，并记录当前已上传的分片数。

请求示例：

POST /api/upload/pause

{

  "uploadId": "b4f8e3a7-1a0c-4a1d-88af-61e98d91a49b"

}

返回示例：

{

  "success": true,

  "message": "任务已暂停"

}

伪代码示例：

@PostMapping("/pause")

public Result pauseUpload(@RequestBody UploadPauseRequest req) {

    // 1. 查找对应的 upload_task

    // 2. 更新任务状态为 “已暂停”

    // 3. 返回任务状态确认信息

}

六、/upload/cancel —— 取消任务

如果用户想放弃本次上传，可以调用 /cancel。
后端会把任务状态标记为“已取消”，并清理对应的临时分片文件。
这样能避免磁盘上堆积无用数据。

请求示例：

POST /api/upload/cancel

{

  "uploadId": "b4f8e3a7-1a0c-4a1d-88af-61e98d91a49b"

}

返回示例：

{

  "success": true,

  "message": "任务已取消"

}

伪代码示例：

@PostMapping("/cancel")

public Result cancelUpload(@RequestBody UploadCancelRequest req) {

    // 1. 查找对应的 upload_task

    // 2. 更新任务状态为 “已取消”

    // 3. 删除或标记已上传的分片文件为待清理

    // 4. 返回操作结果

}

七、/upload/list —— 查询任务列表

这个接口我们用于管理后台查看当前上传任务的整体情况。
可以展示每个任务的文件名、大小、进度、状态、上传人等信息，方便追踪和审计。

请求示例：

GET /api/upload/list

返回示例：

{

  "success": true,

  "data": [

    {

      "uploadId": "b4f8e3a7-1a0c-4a1d-88af-61e98d91a49b",

      "fileName": "training-docs.zip",

      "status": "COMPLETED",

      "uploadedChunks": 320,

      "totalChunks": 320,

      "uploader": "admin",

      "createdAt": "2025-10-20 14:30:12"

    }

  ]

}

伪代码示例：

@GetMapping("/list")

public Result> listUploadTasks() {

    // 1. 查询所有上传任务

    // 2. 按创建时间或状态排序

    // 3. 返回任务摘要信息（任务名、状态、进度、上传人等）

}

接口调用顺序小结

那我们这整个上传过程的调用顺序就是：

1. /upload/check     → 秒传检测

2. /upload/init      → 初始化上传任务

3. /upload/chunk     → 循环上传所有分片

4. /upload/merge     → 所有分片完成后合并

（可选）/upload/pause、/upload/cancel 用于控制任务

（可选）/upload/list 用于任务追踪与审计

接口调用顺序示意图

下面这张时序图展示了前端、后端、数据库在整个上传过程中的交互关系。

这样安排有几个好处：

1. 逻辑衔接顺：上面刚讲完每个接口的职责，下面立刻用图总结；
2. 视觉节奏平衡：读者读到这里已经看了不少文字，用图能缓解阅读疲劳；
3. 承上启下：这张图既总结接口流程，又能自然引出下一节“数据库表设计”。

这套接口设计基本能覆盖大文件上传在企业项目中的常见需求。
接下来，我们再来看看支撑这套接口背后的数据库表设计。
数据库的作用是让上传任务的状态可追踪、可恢复，也能在集群部署时保持一致性。

---

数据库表设计思路

前面说的那一套接口，要真正稳定地跑起来，
后端必须有一套能记录任务状态、分片信息、文件存储路径的数据库结构。
因为上传这种场景不是“一次请求就结束”的操作，它往往会持续几分钟甚至几个小时，
所以我们需要让任务状态可以追踪、可以恢复，还要能支撑集群部署。

我这次主要设计了三张核心表：
upload_task（上传任务表）、upload_chunk（分片表）、file_info（文件信息表）。
它们分别负责记录任务、分片和最终文件三层的数据关系。

一、upload_task —— 上传任务表

这张表是整个上传过程的“总账”，
每一个文件上传任务，不管分成多少片，都会在这里生成一条记录。
它主要用来保存任务的全局信息，比如文件名、大小、上传进度、状态、存储方式等。

CREATE TABLE `upload_task` (

  `id` bigint(20) NOT NULL AUTO_INCREMENT,

  `upload_id` varchar(64) NOT NULL COMMENT '任务唯一ID（UUID）',

  `file_hash` varchar(64) NOT NULL COMMENT '文件哈希（用于秒传与断点续传）',

  `file_name` varchar(255) NOT NULL COMMENT '文件名称',

  `file_size` bigint(20) NOT NULL COMMENT '文件总大小（字节）',

  `chunk_size` bigint(20) NOT NULL COMMENT '每个分片大小（字节）',

  `total_chunks` int(11) NOT NULL COMMENT '分片总数',

  `uploaded_chunks` int(11) DEFAULT '0' COMMENT '已上传分片数量',

  `status` tinyint(4) DEFAULT '0' COMMENT '任务状态：0-待上传 1-上传中 2-合并中 3-完成 4-取消 5-失败 6-已合并 7-已暂停',

  `storage_type` varchar(32) DEFAULT 'local' COMMENT '存储类型：local/oss/cos/minio/s3等',

  `storage_url` varchar(512) DEFAULT NULL COMMENT '文件最终存储地址（云端或本地路径）',

  `local_path` varchar(512) DEFAULT NULL COMMENT '本地临时文件或合并文件路径',

  `remark` varchar(255) DEFAULT NULL COMMENT '备注信息',

  `uploader` varchar(64) DEFAULT NULL COMMENT '上传人',

  `created_at` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',

  `updated_at` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',

  PRIMARY KEY (`id`),

  UNIQUE KEY `upload_id` (`upload_id`),

  KEY `idx_hash` (`file_hash`),

  KEY `idx_status` (`status`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='上传任务表（支持多种云存储）';

设计要点：

• upload_id 是前端初始化任务后由后端生成的唯一标识；
• file_hash 用来支持秒传逻辑；
• status 控制任务生命周期（等待、上传中、合并中、完成等）；
• storage_type、storage_url 可以兼容多种存储方案（本地、OSS、COS、MinIO）；
• uploaded_chunks 字段让任务能随时恢复，适配断点续传。

二、upload_chunk —— 分片表

这张表对应每个上传任务下的所有分片。
每一个分片都会单独在这里占一条记录，用来追踪它的上传状态。
这张表的存在让我们能做断点续传、进度统计、以及合并前的完整性检查。

CREATE TABLE `upload_chunk` (

  `id` bigint(20) NOT NULL AUTO_INCREMENT,

  `upload_id` varchar(64) NOT NULL COMMENT '所属上传任务ID',

  `chunk_index` int(11) NOT NULL COMMENT '分片索引（从0开始）',

  `chunk_size` bigint(20) NOT NULL COMMENT '实际分片大小（字节）',

  `chunk_hash` varchar(64) DEFAULT NULL COMMENT '可选：分片hash（用于高级去重）',

  `status` tinyint(4) DEFAULT '0' COMMENT '状态：0-待上传 1-已上传 2-已合并',

  `local_path` varchar(512) DEFAULT NULL COMMENT '分片本地路径',

  `created_at` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',

  `updated_at` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',

  PRIMARY KEY (`id`),

  UNIQUE KEY `uniq_task_chunk` (`upload_id`,`chunk_index`),

  KEY `idx_upload_id` (`upload_id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='上传分片表';

设计要点：

• upload_id 是任务外键，和 upload_task 一一对应；
• chunk_index 代表分片顺序，合并文件时会按这个排序；
• chunk_hash 可选字段，用来在上传前后做完整性校验；
• status 字段控制上传进度（待上传、已上传、已合并）；
• 唯一索引 (upload_id, chunk_index) 避免重复插入分片。

通过这张表，我们可以轻松实现断点续传：
当用户重新开始上传时，后端只返回未完成的分片索引，前端跳过已上传的部分。

三、file_info —— 文件信息表

这张表记录的是上传完成后的“最终文件信息”，
相当于系统的文件索引表。只要文件合并成功并通过校验，
后端就会往这里写入一条记录。

这张表支撑秒传功能，也能被后续的文档解析或向量化任务使用。

CREATE TABLE `file_info` (

  `id` bigint(20) NOT NULL AUTO_INCREMENT,

  `file_hash` varchar(64) NOT NULL COMMENT '文件hash，用于秒传',

  `file_name` varchar(255) NOT NULL COMMENT '文件名称',

  `file_size` bigint(20) NOT NULL COMMENT '文件大小',

  `storage_type` varchar(32) DEFAULT 'local' COMMENT '存储类型：local/oss/cos/minio/s3等',

  `storage_url` varchar(512) DEFAULT NULL COMMENT '文件最终存储地址（云端或本地路径）',

  `uploader` varchar(64) DEFAULT NULL COMMENT '上传人',

  `status` tinyint(4) DEFAULT '1' COMMENT '状态：1-正常，2-删除中，3-已归档',

  `remark` varchar(255) DEFAULT NULL COMMENT '备注',

  `created_at` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',

  PRIMARY KEY (`id`),

  UNIQUE KEY `file_hash` (`file_hash`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='已上传文件信息表（支持多云存储）';

设计要点：

• file_hash 是全局唯一标识，用于秒传和查重；
• storage_url 记录最终可访问路径；
• status 可扩展为删除、归档等后续操作；
• 这张表和业务系统中的“文档解析”、“知识库构建”可以直接关联。

四、三张表之间的关系

这三张表之间的关系我们可以简单理解为：

upload_task  (上传任务)

    ├── upload_chunk (分片详情)

    └── file_info    (最终文件)

• upload_task 管理任务生命周期；
• upload_chunk 跟踪每个分片的上传进度；
• file_info 保存最终文件索引，用于秒传与后续 AI 处理。

这样设计的好处是：

• 上传状态可追踪；
• 上传任务可恢复；
• 文件信息可统一管理；
• 多节点部署也能保证一致性。

---

上传状态流转与任务恢复机制

有了前面的三张核心表，整个上传的过程就能被“状态机化”管理。
简单来说，我们希望每一个上传任务从创建、上传、合并到完成，都能有一个明确的状态，
系统也能在任意阶段中断后恢复，不需要用户重新来一遍。

我们把整个上传任务的生命周期划分成几个关键状态：

WAITING(0, "待上传"),

UPLOADING(1, "上传中"),

MERGING(2, "合并中"),

COMPLETED(3, "已完成"),

CANCELED(4, "已取消"),

FAILED(5, "上传失败"),

CHUNK_MERGED(6, "已合并"),

PAUSED(7, "已暂停");

一、WAITING（待上传）

当用户在前端发起上传、文件切片还没真正传上来之前，
系统会先生成一个上传任务记录（也就是 /upload/init 接口那一步）。
这个时候任务只是“登记”在数据库里，还没开始传数据。

我们可以理解为：

任务刚创建，还没开始跑。

此时前端拿到 uploadId，就可以开始逐片上传了。

在数据库层面，upload_task.status = 0，所有的分片表里还没有数据。

二、UPLOADING（上传中）

当第一个分片开始上传时，系统会把任务状态更新为 上传中。
这时候每上传一块分片，都会往 upload_chunk 表里写入一条记录，
并且更新任务的 uploaded_chunks 字段。

我们会周期性地根据分片上传数量去更新进度条，
比如已上传 35 / 100 块，系统就知道这部分可以恢复。

这个阶段是任务生命周期里最活跃的一段：
用户可能暂停、断网、刷新页面、甚至浏览器崩溃。
但是没关系，因为分片信息都落地到数据库了，
我们能随时通过 upload_chunk 的状态重新恢复上传。

三、PAUSED（已暂停）

如果用户主动点击“暂停上传”，
系统就会把任务状态标记为 PAUSED。

暂停并不会删除分片，只是告诉系统“不要再继续发请求”。
这样当用户重新点击“继续上传”时，
前端只需从后端拿到“哪些分片还没上传”，就能断点续传。

这个状态一般只在用户控制的情况下出现，
比如网络不好、或者中途切换网络时暂停。

四、CANCELED（已取消）

取消和暂停不同，取消意味着用户彻底放弃了这个上传任务。
任务会被标记为 CANCELED，同时系统可以选择：

• 删除已经上传的临时分片文件；
• 或者保留一段时间等待清理任务。

在后台日志中，这个状态主要用于审计：
记录谁取消了任务、在什么时间、上传了多少进度。

五、MERGING（合并中）

当所有分片都上传完成后，
后端会自动或手动触发文件合并逻辑（调用 /upload/merge）。
此时任务状态会切换为 MERGING，表示系统正在进行最后一步。

在这一步里：

• 如果是本地存储，会逐个读取分片文件并拼接为完整文件；
• 如果是云存储（比如 OSS、MinIO），则会触发服务端的分片合并 API。

合并过程通常比较耗时，尤其是几 GB 的文件，
所以单独拿出来作为一个明确状态是必要的。

六、CHUNK_MERGED（已合并）

有些系统会把合并成功但未做后续处理的状态单独标出来，
比如文件已经合并，但还没入库、还没解析。
这个状态可以让我们在合并之后还有机会做文件校验或后处理。

不过在实际项目里，也可以直接跳过这一步，
合并完后立刻进入下一状态——COMPLETED。

七、COMPLETED（已完成）

文件合并完成、验证通过、存储路径落地、写入 file_info 表，
这时候任务就算彻底完成了。

在这个状态下：

• 用户可以正常访问文件；
• 系统可以执行后续的解析任务（比如文档拆页、向量化等）；
• 文件具备秒传条件，下次再上传同样的文件会直接跳过。

COMPLETED 是整个生命周期的终点状态。
在数据库中，任务记录会更新最终路径、存储类型、完成时间等字段。

八、FAILED（上传失败）

上传过程中如果出现异常，比如网络中断、磁盘写入异常、OSS 上传失败等，
系统会标记任务为 FAILED。
这一状态不会自动清理，
方便管理员事后追踪错误原因或人工恢复。

失败任务在设计上一般允许“重新启动”，
也就是通过任务 ID 重新触发上传，从未完成的分片继续。

我们可以通过下面这张图可以更直观地看到整个上传任务的生命周期：

九、任务恢复机制

在这套机制下，任务恢复就变得非常自然。
前端每次进入上传页面时，只要传入文件的 hash，
后端就能通过 upload_task 和 upload_chunk 判断：

1. 这个文件有没有上传任务；
2. 如果有，哪些分片已经上传；
3. 任务当前状态是什么（暂停、失败还是上传中）。

然后前端只需补传那些未上传的分片即可。
这就是我们常说的 断点续传（Resumable Upload） 。

在集群环境中，这套逻辑同样成立，
因为任务与分片状态都落在数据库，不依赖单台服务器。
无论请求打到哪一台机器，上传进度都是统一可见的。

十、中断后如何续传

在实际使用中，用户上传中断是很常见的。
比如文件太大上传到一半，浏览器突然关了；
或者公司网络断了，机器重启了；
甚至有人直接换了电脑继续操作。

如果系统没有任务恢复机制，那用户每次都得重新传一遍，
尤其是那种几个 G 的文件，不但浪费时间，还容易出错。
所以我们在设计这套上传中心时，
一开始就考虑了“断点续传”和“任务恢复”的问题。

1. 恢复上传靠的其实是数据库里的状态

断点续传的核心逻辑，其实很简单：
我们让任务和分片的状态都写进数据库。

每当用户重新进入上传页面、选中同一个文件时，
前端会先计算出文件的 hash，然后调用 /upload/check 接口。
后端收到 hash 后，会依次去查三张表：

1. 先查 file_info
   如果能查到，说明文件之前已经上传并合并成功，
   这时候直接返回“文件已存在”，前端就能实现“秒传”，不需要重新上传。
2. 查不到 file_info，就去查 upload_task
   如果找到了对应任务，就说明这个文件上传到一半被中断了。
   这时我们会返回这个任务的 uploadId。
3. 再查 `upload_chunk``
   系统会统计出哪些分片已经上传成功，哪些还没传。
   然后返回一个“未完成的分片索引列表”给前端。

前端拿到这些信息后，就能从中断的地方继续往下传，
不用再重复上传已经完成的部分。

2. 前端续传时的流程

前端拿到旧的 uploadId 和未完成分片列表后，
只需要跳过那些已经上传成功的分片，
然后照常调用 /upload/chunk 去上传剩下的部分。

上传过程中，每个分片的状态都会被实时更新到 upload_chunk 表中，
upload_task 表的 uploaded_chunks 也会跟着同步增加。
当所有分片都上传完后，任务状态自动进入 MERGING（合并中）阶段。

所以整个续传过程，其实就是**“基于数据库状态的增量上传”**。
用户不需要额外操作，系统自己就能恢复上次的进度。

3. 任务状态和恢复判断

任务是否允许恢复，系统会根据 upload_task.status 来判断。
大致逻辑是这样的：

状态	是否可恢复	说明
WAITING	可以	任务刚创建，还没开始传
UPLOADING	可以	正在上传中，可以继续
PAUSED	可以	用户主动暂停，可以恢复
FAILED	可以	上传失败，可以重新尝试
CANCELED	不可以	用户主动取消，不再恢复
COMPLETED	不需要	已经完成，直接秒传
MERGING	等待中	系统正在合并，前端等待即可

这套判断逻辑让任务的行为更清晰。
比如用户暂停上传再回来时，可以直接恢复；
如果任务已经取消，那就算用户重启也不会再自动续传。

4. 多机器部署下的恢复问题

有些人会担心：如果我们的系统是集群部署的，
上传时中断后再续传，万一请求打到另一台机器上，
还能恢复吗？

其实没问题。
因为我们所有任务和分片的状态都是写进数据库的，
不依赖内存或本地文件。

也就是说，哪怕用户上次上传在 A 机器，这次续传到了 B 机器，
系统仍然能根据数据库的记录知道：
这个 uploadId 下的哪些分片已经上传完，哪些还没传。

所以集群部署下也能无缝续传，不会出现“不同机器不认任务”的情况。

5. 小结

整个任务恢复机制靠的就是两张表：upload_task 和 upload_chunk。
upload_task 负责记录任务总体进度，
upload_chunk 负责记录每个分片的上传状态。

当用户重新上传时，我们查表判断进度，
前端从未完成的地方继续传，就能实现真正意义上的“断点续传”。

这套机制有几个显著的好处：

• 上传进度可追踪；
• 中断后可恢复；
• 支持集群部署；
• 不依赖浏览器缓存或 Session。

所以，只要数据库没丢，任务记录还在，
上传进度就能恢复，哪怕换机器、重启系统都没问题。

---

文件合并与完整性校验

前面的所有步骤，其实都是在为这一刻做准备。
当用户的所有分片都上传完成后，接下来最重要的工作就是：
把这些分片拼成一个完整的文件，并且确保文件内容没有出错。

这一步看似简单，但其实是整个大文件上传流程里最容易出问题的地方。
尤其在集群部署下，如果不同分片分布在不同机器上，
那合并逻辑就不能只靠本地文件路径去拼接，否则根本找不到所有分片。

所以我们先来理一理整个思路。

一、合并的触发时机

前端在检测到所有分片都上传完成后，会调用 /upload/merge 接口。
这个接口的作用就是通知后端：
“这个任务的所有分片都传完了，现在可以开始合并了。”

后端接收到请求后，会先去查数据库确认几个关键信息：

1. 这个任务对应的 uploadId 是否存在；
2. upload_chunk 表里所有分片是否都处于 “已上传” 状态；
3. 当前任务状态是否允许合并（例如不是暂停、取消或失败）。

确认无误后，任务状态会从 UPLOADING 变成 MERGING，
正式进入文件合并阶段。

二、本地合并逻辑

如果系统配置的是本地存储（也就是 cloud.enable = false），
那所有分片文件都保存在服务器的临时目录中。

合并逻辑大致是这样的：

1. 后端按分片的 chunk_index 顺序，依次读取每个分片文件。
2. 逐个写入到一个新的目标文件中，比如 merge.zip。
3. 每合并一个分片，就更新数据库中的状态。
4. 合并完成后，把任务状态更新为 COMPLETED，并写入最终路径。

整个过程看起来很直观，
但这里有两个要点需要特别注意：

• 写入顺序要严格按照分片索引，否则文件内容会错乱；
• 文件 IO 要用流式写入（Stream） ，避免内存一次性读取所有分片导致溢出。

合并完成后，我们会计算整个文件的 MD5，与原始 fileHash 对比，
如果不一致，就说明合并过程中数据丢失或出错。
这种情况任务会被标记为 FAILED，并在日志中留下异常记录。

三、云端合并逻辑

如果我们配置了云存储（比如 OSS、COS、MinIO 等），
那分片文件就不是存在本地磁盘，而是上传到云端的对象存储桶里。

在这种情况下，合并逻辑就不需要我们自己拼文件了，
因为大部分云存储服务都提供了“分片合并”的 API。

比如以 OSS 为例，上传时我们调用的是 uploadPart 接口，
合并时只需要调用 completeMultipartUpload，
它会根据上传时的分片顺序自动合并为一个完整对象。

整个过程的优点是：

• 不占用本地磁盘；
• 不受单机 IO 限制；
• 云端自动校验每个分片的完整性。

所以在云存储场景下，我们只需要做两件事：

1. 通知云服务去执行合并；
2. 成功后记录最终的文件地址（storage_url）到数据库。

这样整个流程就闭环了。

四、集群部署下的合并问题

单机情况下，合并很简单，因为所有分片都在本地。
但如果系统是集群部署的，分片请求可能打到了不同机器，
这时候分片文件就会分散在多个节点上。

我们在设计时考虑了三种解决方案：

方案 1：共享存储（私有化部署下比较推荐）

最常见的做法是把所有机器的上传目录指向同一个共享路径，
比如通过 NFS、NAS、或对象存储挂载到 /data/uploads。
这样无论用户上传的分片打到哪台机器，
最终都会写入同一个物理目录。

当合并请求发起时，任意一台机器都能访问到完整的分片文件。
这是目前在企业部署中最稳定、最通用的方案。

方案 2：云存储中转

如果机器之间没有共享目录，那我们可以让每个分片先上传到云端，
合并时再调用云服务的 API 进行分片合并。
这种方式适合公网可访问的 SaaS 环境。
但对于政企内网部署，就不一定行得通。

方案 3：统一调度节点

还有一种是我们自己维护一个“合并调度节点”，
所有分片上传完后，系统会把合并任务分配到一个指定节点执行，
这个节点会从其他机器拉取分片（比如通过 HTTP 内部传输或 RPC）。
这种方式更复杂，适合大规模分布式存储场景。

在私有化项目中，我们一般采用第一种方式——共享目录 + 本地合并。
既能保证性能，也能兼顾安全性。

五、完整性校验

文件合并完成后，最后一步是完整性校验。
我们会重新计算合并后文件的 MD5，与前端最初上传的 fileHash 对比。

如果一致，就说明文件合并成功，内容没有丢失；
如果不一致，就说明某个分片损坏或顺序错误，
任务会被标记为 FAILED，并自动记录错误日志。

这样可以确保文件数据的安全性，
避免在后续 AI 解析或向量化阶段出现内容异常。

六、异步处理与性能优化

开头的视频里我们也看到了，整个上传和合并过程我们是同步执行的。
从前端开始上传分片，到最后文件合并完成，都在等待同一个流程走完。
这种方式在演示时很直观，但在真实项目中其实问题不少。

最明显的一个问题就是——时间太长。
像我们刚才那个 1GB 的文件，即使网络稳定、服务器性能还可以，
整个流程也要几分钟甚至更久。
如果我们让前端一直等待响应，接口超时、连接断开、前端刷新这些问题就都会冒出来。

所以，在真正的业务系统里，我们一般会把合并、校验、迁移 OSS 或解析入库这些操作改成异步任务来做。
接口只负责接收分片、登记状态，然后立刻返回“任务已创建”或“上传完成，正在处理中”的提示。
后续的合并、校验、清理临时文件这些工作交给后台的异步线程、任务队列或者调度器去跑。

这样做的好处有几个：

• 前端体验更流畅，不用卡在“等待合并”阶段；
• 后端可以批量处理任务，减少高峰期的 IO 压力；
• 如果任务失败或中断，也能通过任务表重试或补偿；
• 对接外部存储或 AI 解析流程时，也能自然衔接后续任务链。

简单来说，上传只是第一步，
而合并、校验、转存这些操作本质上更像是后台任务。
我们在系统设计时只要把这些环节分开，让接口尽量“轻”，
这套上传系统就能在面对更大文件、更复杂场景时依然稳定可靠。

七、小结

整个合并与校验阶段，是把前面所有分片上传工作“收尾”的过程。
我们通过以下机制保证了稳定性：

• 本地存储场景下：顺序读取 + 流式写入 + hash 校验；
• 云存储场景下：依赖云端分片合并 API；
• 集群环境下：通过共享存储或统一调度节点解决文件分散问题；
• 数据库层面：实时记录状态，便于追踪和审计。

最终，当文件合并成功、校验通过后，
系统会将结果写入 file_info 表，
整条上传链路就算是完整闭环。

---

最后

我们平常做的项目，大多数时候文件上传都挺简单的。
前端传到 OSS，后端接个地址存起来就行。
但等真正做私有化项目的时候，也就会发现很多地方都不一样了。
要求更多，考虑的细节也多得多。

像这次做的大文件上传就是个很典型的例子。
以前那种简单方案，放在这种环境下就完全不够用了。
得考虑断点续传、任务恢复、集群部署、权限、审计这些东西，
一步没想好，后面全是坑。

我们现在这套设计，其实就是在解决这些“现实问题”。
接口虽然多一点，但每个职责都很清晰，
任务状态能追踪，上传中断能恢复，
甚至以后如果我们想单独抽出来做一个文件系统模块也完全没问题。
不管是拿来给知识库用，还是 AI 向量化、文档解析，这套逻辑都能复用。

其实很多以前觉得“简单”的功能，
一旦遇到复杂场景，其实都得重新想。
但好处是，一旦做通了，这套东西就能稳定用很久。

到这里，大文件上传这块我们算是完整走了一遍。
以后再遇到类似需求，我们就有经验了，
不用再从头掉坑里爬出来一次哈。

更多架构实战、工程化经验和踩坑复盘，我会在公众号 「洛卡卡了」 持续更新。
如果内容对你有帮助，欢迎关注我，我们一起每天学一点，一起进步。

作者：洛卡卡了
来源：juejin.cn/post/7571355989133099023

你一定见过无数臃肿的 if-else 和重复嵌套的逻辑。在追求 AI-Native 开发的今天，代码的“原子化”程度直接决定了 AI 辅助重构的效率。

柯里化（Currying） 绝不仅仅是面试时的八股文，它是实现逻辑复用、配置解耦的工业级利器。通俗地说，它把一个多参数函数拆解成一系列单参数函数：$f(a, b, c) \rightarrow f(a)(b)(c)$。

以下是 8 个直击前端实战痛点的柯里化应用案例。

1. 差异化日志系统：环境与等级的解耦

在web系统中，我们经常需要根据不同环境输出不同等级的日志。

JavaScript

const logger = (env) => (level) => (msg) => {

  console.log(`[${env.toUpperCase()}][${level}] ${msg} - ${new Date().toLocaleTimeString()}`);

};



const prodError = logger('prod')('ERROR');

const devDebug = logger('dev')('DEBUG');



prodError('支付接口超时'); // [PROD][ERROR] 支付接口超时 - 10:20:00

2. API 请求构造器：预设 BaseURL 与 Header

不用每次请求都传 Token 或域名，通过柯里化提前“锁死”配置。

JavaScript

const request = (baseUrl) => (headers) => (endpoint) => (params) => {

  return fetch(`${baseUrl}${endpoint}?${new URLSearchParams(params)}`, { headers });

};



const apiWithAuth = request('https://api.finance.com')({ 'Authorization': 'Bearer xxx' });

const getUser = apiWithAuth('/user');



getUser({ id: '888' }); 

3. DOM 事件监听：优雅传递额外参数

在 Vue 或 React 模板中，我们常为了传参写出 () => handleClick(id)。柯里化可以保持模板整洁并提高性能。

JavaScript

const handleMenuClick = (menuId) => (event) => {

  console.log(`点击了菜单: ${menuId}`, event.target);

};



// 模板中直接绑定：@click="handleMenuClick('settings')"

4. 复合校验逻辑：原子化验证规则

将复杂的表单校验拆解为可组合的原子。

JavaScript

const validate = (reg) => (tip) => (value) => {

  return reg.test(value) ? { pass: true } : { pass: false, tip };

};



const isMobile = validate(/^1[3-9]\d{9}$/)('手机号格式错误');

const isEmail = validate(/^\w+@\w+.\w+$/)('邮箱格式错误');



console.log(isMobile('13800138000')); // { pass: true }

5. 金融汇率换算：固定基准率

在处理多币种对账时，柯里化能帮你固定变动较慢的参数。

JavaScript

const convertCurrency = (rate) => (amount) => (amount * rate).toFixed(2);



const usdToCny = convertCurrency(7.24);

const eurToCny = convertCurrency(7.85);



console.log(usdToCny(100)); // 724.00

6. 动态 CSS 类名生成器：样式逻辑解耦

配合 CSS Modules 或 Tailwind 时，通过柯里化快速生成带状态的类名。

JavaScript

const createCls = (prefix) => (state) => (baseCls) => {

  return `${prefix}-${baseCls} ${state ? 'is-active' : ''}`;

};



const navCls = createCls('nav')(isActive);

const btnCls = navCls('button'); // "nav-button is-active"

7. 数据过滤管道：可组合的 Array 操作

在处理海量 AI Prompt 列表时，将过滤逻辑函数化，方便链式调用。

JavaScript

const filterBy = (key) => (value) => (item) => item[key].includes(value);



const filterByTag = filterBy('tag');

const prompts = [{ title: 'AI助手', tag: 'Finance' }, { title: '翻译机', tag: 'Tool' }];



const financePrompts = prompts.filter(filterByTag('Finance'));

8. AI Prompt 模板工厂：多层上下文注入

为你正在开发的 AI Prompt Manager 设计一个分层注入器：先注入角色，再注入上下文，最后注入用户输入。

JavaScript

const promptFactory = (role) => (context) => (input) => {

  return `Role: ${role}\nContext: ${context}\nUser says: ${input}`;

};



const financialExpert = promptFactory('Senior Financial Analyst')('Analyzing 2026 Q1 Report');

const finalPrompt = financialExpert('请总结该季报风险点');

<!DOCTYPE html>

<html lang="zh-CN">

<head>

  <meta charset="UTF-8" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>

  <title>Flip Clock</title>

  <style>

    body {

      background: #111;

      display: flex;

      justify-content: center;

      align-items: center;

      height: 100vh;

      margin: 0;

      font-family: 'Courier New', monospace;

      color: white;

    }



    .clock {

      display: flex;

      gap: 20px;

    }



    .card-container {

      width: 80px;

      height: 120px;

      position: relative;

      perspective: 500px;

      background: #2c292c;

      border-radius: 8px;

      box-shadow: 0 4px 12px rgba(0,0,0,0.5);

    }



    /* 中间分割线 */

    .card-container::before {

      content: "";

      position: absolute;

      left: 0;

      top: 50%;

      width: 100%;

      height: 4px;

      background: #120f12;

      z-index: 10;

    }



    .card-item {

      position: absolute;

      width: 100%;

      height: 50%;

      left: 0;

      overflow: hidden;

      background: #2c292c;

      color: white;

      text-align: center;

      font-size: 64px;

      font-weight: bold;

      backface-visibility: hidden;

      transition: transform 0.4s ease-in-out;

    }



    /* 下层数字：初始对折（背面朝上） */

    .card1 { /* 下层上半 */

      top: 0;

      line-height: 120px; /* 整体高度对齐 */

    }

    .card2 { /* 下层下半 */

      top: 50%;

      line-height: 0;

      transform-origin: center top;

      transform: rotateX(180deg);

      z-index: 2;

    }



    /* 上层数字：当前显示 */

    .card3 { /* 上层上半 */

      top: 0;

      line-height: 120px;

      transform-origin: center bottom;

      z-index: 3;

    }

    .card4 { /* 上层下半 */

      top: 50%;

      line-height: 0;

      z-index: 1;

    }



    /* 翻页动画触发 */

    .flip .card2 {

      transform: rotateX(0deg);

    }

    .flip .card3 {

      transform: rotateX(-180deg);

    }



    /* 冒号分隔符 */

    .colon {

      font-size: 64px;

      display: flex;

      align-items: center;

      color: #aaa;

    }

  </style>

</head>

<body>

  <div class="clock">

    <div class="card-container flip" id="hour" data-number="00">

      <div class="card1 card-item">00</div>

      <div class="card2 card-item">00</div>

      <div class="card3 card-item">00</div>

      <div class="card4 card-item">00</div>

    </div>



    <div class="colon">:</div>



    <div class="card-container flip" id="minute" data-number="00">

      <div class="card1 card-item">00</div>

      <div class="card2 card-item">00</div>

      <div class="card3 card-item">00</div>

      <div class="card4 card-item">00</div>

    </div>



    <div class="colon">:</div>



    <div class="card-container flip" id="second" data-number="00">

      <div class="card1 card-item">00</div>

      <div class="card2 card-item">00</div>

      <div class="card3 card-item">00</div>

      <div class="card4 card-item">00</div>

    </div>

  </div>



  <script>

    function setHTML(dom, nextValue) {

      const curValue = dom.dataset.number;

      if (nextValue === curValue) return;



      // 更新 DOM 结构：下层为新值，上层为旧值

      dom.innerHTML = `

        <div class="card1 card-item">${nextValue}</div>

        <div class="card2 card-item">${nextValue}</div>

        <div class="card3 card-item">${curValue}</div>

        <div class="card4 card-item">${curValue}</div>

      `;



      // 触发重绘以重启动画

      dom.classList.remove('flip');

      void dom.offsetWidth; // 强制重排

      dom.classList.add('flip');



      dom.dataset.number = nextValue;

    }



    function updateClock() {

      const now = new Date();

      const h = String(now.getHours()).padStart(2, '0');

      const m = String(now.getMinutes()).padStart(2, '0');

      const s = String(now.getSeconds()).padStart(2, '0');



      setHTML(document.getElementById('hour'), h);

      setHTML(document.getElementById('minute'), m);

      setHTML(document.getElementById('second'), s);

    }



    // 初始化

    updateClock();

	// setTimeout(updateClock,1000)

	

    setInterval(updateClock, 1000);

  </script>

</body>

</html>

这个翻页时钟（Flip Clock）通过 CSS 3D 变换 + 动画类切换 + DOM 内容动态更新 的方式，模拟了类似机械翻页牌的效果。下面从结构、样式和逻辑三方面详细分析其实现原理：

🔧 一、HTML 结构设计

每个时间单位（小时、分钟、秒）由一个 .card-container 容器表示，内部包含 4 个 .card-item 元素：

<div class="card-container" id="second">

  <div class="card1">00</div> <!-- 下层上半 -->

  <div class="card2">00</div> <!-- 下层下半（初始翻转180°）-->

  <div class="card3">00</div> <!-- 上层上半（当前显示）-->

  <div class="card4">00</div> <!-- 上层下半 -->

</div>

四个卡片的作用：

• .card3 和 .card4：组成当前显示的数字（上半+下半），正常显示。


• .card1 和 .card2：组成即将翻出的新数字，但初始时 .card2 被 rotateX(180deg) 翻转到背面（不可见）。


• 中间有一条 ::before 伪元素作为“折痕”，增强翻页视觉效果。

🎨 二、CSS 样式与 3D 翻转原理

关键 CSS 技术点：

1. 3D 空间设置

.card-container {

  perspective: 500px; /* 创建 3D 视角 */

}

• perspective 让子元素的 3D 变换有景深感。

2. 上下两半的定位与旋转轴

.card2 {

  transform-origin: center top;

  transform: rotateX(180deg); /* 初始翻到背面 */

}

.card3 {

  transform-origin: center bottom;

}

• .card2 绕顶部边缘旋转 180°，藏在下方背面。


• .card3 绕底部边缘旋转，用于向上翻折。

3. 翻页动画（通过 .flip 类触发）

.flip .card2 {

  transform: rotateX(0deg); /* 展开新数字下半部分 */

}

.flip .card3 {

  transform: rotateX(-180deg); /* 当前数字上半部分向上翻折隐藏 */

}

• 动画持续 0.4s，使用 ease-in-out 缓动。


• .card1 和 .card4 始终保持静态，作为背景支撑。

✅ 视觉效果：

• 上半部分（.card3）向上翻走（像书页翻开）


• 下半部分（.card2）从背面转正，露出新数字


• 中间的“折痕”让翻页更真实

⚙️ 三、JavaScript 动态更新逻辑

核心函数：setHTML(dom, nextValue)

步骤分解：

时间更新：

• 每秒调用 updateClock()，获取当前时分秒（两位数格式）。


• 分别调用 setHTML 更新三个容器。

🌟 四、为什么能实现“翻页”错觉？

💡 关键技巧：

• 利用 两个完整数字（新+旧）叠加，通过控制上下半部分的旋转，制造“翻页”而非“淡入淡出”。


• 强制重排（offsetWidth） 是确保 CSS 动画每次都能重新触发的经典 hack。

✅ 总结

这个 Flip Clock 的精妙之处在于：

这是一种典型的 “用 2D DOM 模拟 3D 物理效果” 的前端动画范例，既高效又视觉惊艳。

前言：由于“无处安放”而引发的混乱

在 HTML5 普及之前，前端开发者为了在 DOM 元素上绑定一些数据（比如用户 ID、商品价格、状态码），可谓是八仙过海，各显神通：

直到 HTML5 引入了 data-*  自定义数据属性，这一切终于有了“官方标准”。

第一阶段：基础——它长什么样？

data-* 属性允许我们在标准 HTML 元素中存储额外的页面私有信息。

1. HTML 写法

语法非常简单：必须以 data- 开头，后面接上你自定义的名称。

<!-- ❌ 错误示范：不要大写，不要乱用特殊符号 -->

<div data-User-Id="1001"></div> 



<!-- ✅ 正确示范：全小写，连字符连接 -->

<div 

  id="user-card"

  data-id="1001" 

  data-user-name="juejin_expert" 

  data-value="99.9"

  data-is-vip="true"

>

  用户信息卡片

</div>

2. CSS 中的妙用

很多人以为 data-* 只是给 JS 用的，其实 CSS 也能完美利用它。

场景一：通过属性选择器控制样式

/* 当 data-is-vip 为 "true" 时，背景变金 */

div[data-is-vip="true"] {

  background: gold;

  border: 2px solid orange;

}

场景二：利用 attr() 显示数据

这是一个非常酷的技巧，可以用来做 Tooltip 或者计数器显示。

div::after {

  /* 直接把 data-value 的值显示在页面上 */

  content: "当前分值: " attr(data-value);

  font-size: 12px;

  color: #666;

}

第二阶段：进阶——JavaScript 如何读写？

这才是重头戏。在 JS 中操作 data-* 有两种方式：传统派 和 现代派。

1. 传统派：getAttribute / setAttribute

这是最稳妥的方法，兼容性最好（虽然现在也没人要兼容 IE6 了）。

const el = document.getElementById('user-card');



// 读取

const userId = el.getAttribute('data-id'); // "1001"



// 修改

el.setAttribute('data-value', '100');

特点：读出来永远是字符串。哪怕你存的是 100，取出来也是 "100"。

2. 现代派：dataset API (推荐 ✨)

HTML5 为每个元素提供了一个 dataset 对象（DOMStringMap），它将所有的 data-* 属性映射成了对象的属性。

这里有个大坑（或者说是规范），请务必注意：

HTML 中的 连字符命名 (kebab-case)  会自动转换为 JS 中的 小驼峰命名 (camelCase) 。

const el = document.getElementById('user-card');



// 1. 访问 data-id

console.log(el.dataset.id); // "1001"



// 2. 访问 data-user-name (注意变身了！)

console.log(el.dataset.userName); // "juejin_expert"

// ❌ el.dataset.user-name 是语法错误

// ❌ el.dataset['user-name'] 是 undefined



// 3. 修改数据

el.dataset.value = "200"; 

// HTML 会自动变成 data-value="200"



// 4. 删除数据

delete el.dataset.isVip;

// HTML 中的 data-is-vip 属性会被移除

💡 敲黑板：dataset 里的属性名不支持大写字母。如果你在 HTML 里写 data-MyValue="1", 浏览器会强制转为小写 data-myvalue，JS 里就得用 dataset.myvalue 访问。所以，HTML 里老老实实全小写吧。

第三阶段：深入——类型陷阱与性能权衡

1. 一切皆字符串

不管你赋给 dataset 什么类型的值，最终都会被转为字符串。

el.dataset.count = 100;        // HTML: data-count="100"

el.dataset.active = true;      // HTML: data-active="true"

el.dataset.config = {a: 1};    // HTML: data-config="[object Object]" -> 灾难！

避坑指南：

• 如果你要存数字，取出来时记得 Number(el.dataset.count)。


• 如果你要存布尔值，判断时不能简单用 if (el.dataset.active)，因为 "false" 字符串也是真值！要用 el.dataset.active === 'true'。


• 千万不要试图在 data-* 里存复杂的 JSON 对象。如果非要存，请使用 JSON.stringify()，但在 DOM 上挂载大量字符串数据会影响性能。

2. 性能考量

• 读写速度：dataset 的访问速度在现代浏览器中非常快，但在极高频操作下（比如每秒几千次），直接操作 JS 变量肯定比操作 DOM 快。


• 重排与重绘：修改 data-* 属性会触发 DOM 变更。如果你的 CSS 依赖属性选择器（如 div[data-status="active"]），修改属性可能会触发页面的重排（Reflow）或重绘（Repaint）。

第四阶段：实战——优雅的事件委托

data-value 最经典的用法之一就是在列表项的事件委托中。

需求：点击列表中的“删除”按钮，删除对应项。

<ul id="todo-list">

  <li>

    <span>学习 HTML5</span>

    <!-- 把 ID 藏在这里 -->

    <button class="btn-delete" data-id="101" data-action="delete">删除</button>

  </li>

  <li>

    <span>写掘金文章</span>

    <button class="btn-delete" data-id="102" data-action="delete">删除</button>

  </li>

</ul>

const list = document.getElementById('todo-list');



list.addEventListener('click', (e) => {

  // 利用 dataset 判断点击的是不是删除按钮

  const { action, id } = e.target.dataset;



  if (action === 'delete') {

    console.log(`准备删除 ID 为 ${id} 的条目`);

    // 这里发送请求或操作 DOM

    // deleteItem(id);

  }

});

为什么这么做优雅？

你不需要给每个按钮都绑定事件，也不需要去分析 DOM 结构（比如 e.target.parentNode...）来找数据。数据就在元素身上，唾手可得。

总结与“禁忌”

HTML5 的 data-* 属性是连接 DOM 和数据的一座轻量级桥梁。

什么时候用？

• 当需要把少量数据绑定到特定 UI 元素上时。


• 当 CSS 需要根据数据状态改变样式时。


• 做事件委托需要传递参数时。

什么时候别用？（禁忌）

最后一句：

代码整洁之道，始于不再乱用 Class。下次再想存个 ID，记得想起那个以 data- 开头的帅气属性。

Happy Coding! 🚀

在现代 Web 开发中，技术 SEO 是确保网站能够被搜索引擎正确索引和排名的关键。

不做 SEO：

• 网站处于隐形状态：除非用户直接输入网站，否则没人能通过搜索找到你的网站


• 收录混乱：搜索引擎不收录你的页面，或是收录的无效页面


• 仅能靠付费推广：想要流量只能付费做广告或者社交媒体推广


• 裸链接：用户分享网址时只能是蓝色 URL 链接，可能被识别为垃圾信息


• 品牌信任度：用户难以搜索到网站，降低网站的可信度

做了 SEO：

• 主动被发现：搜索关键词时你的网站会得到推荐，增加流量


• 收录全面：搜索引擎知道网站有哪些页面，网站内容更新后会很快被搜索到


• 免费且持久：搜索引擎会长期维护你的网站，排名稳定后，会有源源不断的流量


• 优雅的展示封面：分享会展示精美的网站封面，提升用户点击率


• 技术红利：做了 SEO，会优化内容结构，变相提升网站的技术


• 背书效应：用户潜意识里认为排在前面的网站更权威、更正规

SEO 这么有用，但一般人的实现却是：

• 加个 <title> 标签


• 加几个 <meta> 关键词

真正有用、高效的 SEO 要怎么做呢？

SEO 核心概念

先来了解一下 SEO 的一些核心概念。

sitemap.xml 是什么？

• 作用：给搜索引擎指路


• 功能：
  
  
  
  
  • 列出你希望被收录的所有页面
  
  
  • 告诉页面更新时间、优先级
  
  
  
  


• 示例

<url>

  <loc>https://xxx.com/page1</loc>

  <lastmod>2026-02-12</lastmod>

  <priority>0.8</priority>

</url>

robots.txt 是什么？

• 作用：给搜索引擎定规矩


• 功能：
  
  
  
  
  • 禁止某些爬虫
  
  
  • 禁止爬某些目录 / 页面
  
  
  • 告诉爬虫去哪里找 sitemap
  
  
  
  


• 示例

User-agent: *

Disallow: /admin/

Disallow: /private.html

Allow: /

Sitemap: https://xxx.com/sitemap.xml

Schema.org 是什么？

• 作用

给 Google、百度、必应 等搜索引擎看的，告诉它们：

• 这是什么内容（文章？产品？视频？人？）


• 标题是什么


• 发布时间


• 作者


• 评分


• 目录结构


• 功能
  
  
  
  
  • 让搜索结果更美观、更丰富（显示标题、图、时间、作者）
  
  
  • 让搜索引擎更懂你页面内容
  
  
  • 提升 SEO 效果
  
  
  
  


• 示例

<script type="application/ld+json">

  {

    "@context": "https://schema.org",

    "@type": "Article",

    "headline": "文章标题",

    "author": { "@type": "Person", "name": "作者" }

  }

</script>

OG Image 是什么？

当你把网页分享到微信、QQ、抖音、小红书、Discord、Facebook时，显示的那张封面图，就是 OG Image。

• 作用
  
  
  
  
  • 控制分享出去长什么样
  
  
  • 没有它，分享可能没封面图、显示效果差
  
  
  
  


• 功能
  
  
  
  
  • 优化分享效果
  
  
  • 提升社交媒体分享的点击率和用户互动
  
  
  
  


• 示例

<meta property="og:title" content="标题" />

<meta property="og:description" content="描述" />

<meta property="og:image" content="https://xxx.com/cover.jpg" />

Nuxt SEO

Nuxt SEO 是一套 SEO 元模块，其中包含多个模块：

核心优势：

• 自动化：自动生成 robots.txt、sitemap.xml 和 og:image。


• 最佳实践：默认遵循 Google 等搜索引擎的推荐标准。


• 开发体验：与 Nuxt DevTools 深度集成，提供实时的 SEO 调试能力。

快速开始

了解完以上概念后，接下来开始提升网站的 SEO 效果。

安装

pnpm i @nuxtjs/seo

配置

在 nuxt.config.ts 中进行配置。最重要的是设置 site.url，它是生成 Sitemap 和 Canonical URL 的基础。

export default defineNuxtConfig({

  modules: ["@nuxtjs/seo"],

  site: {

    url: "https://example.com", // 网站域名

    name: "我的 Nuxt 应用",

    description: "一个高性能的 Nuxt 网站",

    defaultLocale: "zh-CN", // 设置默认语言

  },

})

开发调试

安装了 @nuxtjs/seo 后，启动项目打开 Nuxt DevTools，你会发现一个新的 SEO 选项卡：

• 实时检查：查看当前页面的 Meta 标签、OG 图片预览和 Schema 数据。


• 缺失提示：如果页面缺少关键的 SEO 信息（如 Title 或 Description），DevTools 会给出警告。

进阶配置

虽然 @nuxtjs/seo 已经提供了开箱即用的配置，但在实际生产环境中，我们往往需要更精细的控制。

@nuxtjs/sitemap

sitemap.xml 是搜索引擎发现你网站页面的地图。@nuxtjs/sitemap 模块会自动扫描你的静态路由，但对于动态内容（如博客文章、商品详情），我们需要手动告知它。

常用配置

// nuxt.config.ts

export default defineNuxtConfig({

  sitemap: {

    // 1. 动态路由数据源：支持 API 端点

    sources: ["/api/__sitemap__/urls"],

    // 2. 排除不需要被索引的页面

    exclude: ["/user/**", "/admin/**", "/checkout"],

    // 3. 开启分块 (Chunking)：适用于大型网站 (> 50k URL)

    sitemaps: true,

  },

})

★

对于动态路由，你可以创建一个 Server API (例如 server/api/__sitemap__/urls.ts) 来返回所有的文章链接。

如何验证配置是否生效？

本地启动项目，访问：http://localhost:3000/sitemap.xml；线上环境访问：https://yoursite.com/sitemap.xml，当看到 xml 内容既配置成功。

@nuxtjs/robots

robots.txt 定义了爬虫可以访问哪些区域。@nuxtjs/robots 的一大优势是它能根据环境自动切换策略：开发环境默认禁止所有爬虫，生产环境默认允许。

// nuxt.config.ts

export default defineNuxtConfig({

  robots: {

    // 1. 全局爬虫规则（User-agent: * 对应 allRobots）

    allRobots: {

      // 禁止爬取的目录/页面（常用）

      Disallow: [

        "/admin/", // 后台管理页

        "/api/", // 接口目录

        "/_nuxt/", // Nuxt 打包后的静态资源（可选，一般无需禁止）

        "/private/", // 私有页面

        "/*.pdf$", // 禁止爬取所有 PDF 文件（正则写法）

      ],

      // 允许爬取的内容（覆盖 Disallow，可选）

      Allow: [

        "/api/public/", // 允许爬取公开接口

      ],

      // 爬虫抓取频率（可选，只是建议，非强制）

      CrawlDelay: 2, // 每次请求间隔 2 秒，减轻服务器压力

    },

    // 添加自定义规则

    groups: [

      {

        userAgent: ["Baiduspider"], // 针对百度爬虫的特殊规则

        disallow: ["/api/"], // 禁止访问

        allow: ["/api/public-data"], // 允许访问

      },

      {

        userAgent: "*",

        disallow: ["/secret", "/admin"],

        allow: "/",

      },

    ],

  },

})

如何验证配置是否生效？

本地启动项目，访问：http://localhost:3000/robots.txt；线上环境访问：https://yoursite.com/robots.txt，会看到以下内容:

User-agent: *

Disallow: /admin/

Disallow: /api/

Disallow: /private/

Allow: /

Crawl-delay: 2

Sitemap: https://你的域名.com/sitemap.xml



User-agent: Baiduspider

Disallow: /archive/

nuxt-og-image

全局配置

// nuxt.config.ts

export default defineNuxtConfig({

  modules: ["@nuxtjs/seo"],

  // Nuxt SEO 模块核心配置

  seo: {

    // 基础站点信息（会自动复用为 OG 基础信息）

    site: {

      // ...

    },

    // OG 标签全局配置（重点：ogImage）

    og: {

      // 全局默认 OG 类型

      type: "website",

      // 全局默认 OG Image 配置（核心）

      image: {

        // 图片路径：推荐用绝对路径，或相对路径（模块会自动拼接 site.url）

        src: "/og-default.jpg", // 等价于 https://你的域名.com/og-default.jpg

        width: 1200, // 最优尺寸

        height: 630,

        type: "image/jpeg", // 图片格式

        alt: "网站默认分享封面", // 图片描述（可选，提升可访问性）

      },

      // 全局默认语言

      locale: "zh_CN",

    },

    // 兼容 Twitter 卡片（可选，自动复用 ogImage）

    twitter: {

      card: "summary_large_image", // 大图卡片样式

    },

  },

})

单页面配置

单页面配置的内容会覆盖全局配置。

在具体页面（如 pages/article/[id].vue）中，用 useOgImage 或 useSeoMeta 自定义该页面的 OG Image：

<template>

  <div>详情页</div>

</template>



<script setup lang="ts">

  // 1. 假设从接口获取文章数据

  const article = await fetchArticleData() // 你的业务逻辑

  const articleCover = article.coverImage || "/og-article-default.jpg"



  // 2. 方式1：单独修改 OG Image（推荐，更精准）

  useOgImage({

    src: articleCover, // 自定义封面图路径

    width: 1200,

    height: 630,

    alt: article.title, // 用文章标题作为图片描述

  })



  // 3. 方式2：批量修改 OG 信息（含 Image）

  useSeoMeta({

    ogTitle: article.title, // 文章标题

    ogDescription: article.summary, // 文章摘要

    ogImage: [

      {

        src: articleCover,

        width: 1200,

        height: 630,

      },

    ],

    twitterImage: articleCover, // 兼容 Twitter

  })

</script>

动态路由批量配置

动态页面的配置可以结合sitemap来设置：

// nuxt.config.ts

export default defineNuxtConfig({

  modules: ["@nuxtjs/seo"],

  sitemap: {

    // 动态生成路由 + 对应 OG Image

    routes: async () => {

      const articles = await fetchAllArticles() // 获取所有文章

      return articles.map((article) => ({

        url: `/article/${article.id}`,

        // 给每个路由绑定 OG Image

        seo: {

          ogImage: {

            src: article.coverImage,

            width: 1200,

            height: 630,

          },

        },

      }))

    },

  },

})

如何验证配置是否生效？

启动项目，访问页面右键「页面源代码」，能看到 <meta property="og:image" content="你的图片URL"> 即配置成功。

SEO 进阶技巧与最佳实践

1. 喂饱搜索引擎

搜索引擎喜欢结构化数据。通过 Schema.org 标记，你可以让 Google 更精准地理解你的内容。

Nuxt SEO 提供了 useSchemaOrg 组合式函数，让你可以像写 Vue 组件一样编写 Schema：

<script setup lang="ts">

  useSchemaOrg([

    defineArticle({

      image: '/images/cover.jpg',

      datePublished: '2026-02-18',

      author: {

        name: 'Trae',

      },

    })

  ])

</script>

2. 社交分享优化

当用户将你的链接分享到 Twitter 或微信时，一张精美的预览图能显著提高点击率。

• Open Graph 标签：自动生成 og:title, og:description 等标签。


• OG Image 生成：nuxt-og-image 模块可以根据你的页面内容（标题、摘要）动态生成 SVG 或 PNG 图片。这意味着你不需要为每篇文章手动通过 Photoshop 制作封面，代码即设计！

3. 链接与 URL 规范化

重复内容是 SEO 的大忌。Nuxt SEO 能帮你处理这些细节：

• Trailing Slashes：统一 URL 结尾是否带斜杠（例如 /about vs /about/），避免被视为两个页面。


• Canonical URLs：自动添加规范链接，告诉搜索引擎哪个是"正版"页面，防止参数（如 ?utm_source=...）导致权重分散。

多搜索引擎适配策略

不同的搜索引擎有不同的脾气，针对国内外的搜索巨头，可以采取差异化的策略。

Google 优化

Google 的爬虫能力最强，能够很好地执行 JavaScript。

• Core Web Vitals：重点关注 LCP (最大内容绘制)、CLS (累积布局偏移) 和 INP (交互到下一次绘制)。Nuxt 默认的性能优化通常能满足要求。


• Google Search Console：在 GSC 中主动提交你的 sitemap.xml，并定期查看"覆盖率"报告，修复 404 和 500 错误。


• 富媒体搜索结果：利用上文提到的 Schema 标记，争取在搜索结果中展示星级评分、问答等富媒体信息。

百度优化

百度爬虫对现代 JavaScript 的执行能力相对较弱，且对页面加载速度极其敏感。

• 确保 SSR 输出：这是最关键的一点。确保你的 Nuxt 应用以 SSR 模式运行，并且 HTML 源码中直接包含核心内容。
  
  
  
  
  • 验证方法：在终端运行 curl https://your-site.com，检查返回的 HTML 是否包含你的内容。
  
  
  
  


• 主动推送：百度非常依赖主动提交。看在网站上线后，通过 API 立即将链接推送到百度站长平台。


• URL 结构：百度更喜欢扁平、简单的 URL 结构，避免过深的层级和复杂的动态参数。


• 移动端适配：百度对移动端友好的站点有明显的加权，做好响应式适配移动端是一个不错的选择。

必应优化

Bing 在搜索端的占比越来越高，且是 ChatGPT 搜索的数据源之一。

• IndexNow 协议：Bing 大力推广 IndexNow 协议，允许网站在一个 URL 发生变化时立即通知搜索引擎。这比传统的 Sitemap 被动抓取要快得多。


• Bing Webmaster Tools：功能与 GSC 类似，建议注册并提交 Sitemap。

总结

SEO 是一个长期积累的过程，但 Nuxt SEO 模块帮我们扫清了技术障碍。通过合理的配置和使用，并针对 Google、百度等不同平台进行针对性优化，可以确保你的 Nuxt 应用在起跑线上就领先一步。

🔗 项目地址: nuxtseo.com

👍作品推荐

Haotab 新标签页，一个优雅的新标签页

chrome 商店
| edge 商店
| 在线版

❤️静待你的体验

同学们好，我是 Eugene（尤金），一个拥有多年中后台开发经验的前端工程师~

（Eugene 发音很简单，/juːˈdʒiːn/，大家怎么顺口怎么叫就好）

你是否也有过：明明学过很多技术，一到关键时候却讲不出来、甚至写不出来？

你是否也曾怀疑自己，是不是太笨了，明明感觉会，却总差一口气？

就算想沉下心从头梳理，可工作那么忙，回家还要陪伴家人。

一天只有24小时，时间永远不够用，常常感到力不从心。

技术行业，本就是逆水行舟，不进则退。

如果你也有同样的困扰，别慌。

从现在开始，跟着我一起心态归零，利用碎片时间，来一次彻彻底底的基础扫盲。

这一次，我们一起慢慢来，扎扎实实变强。

不搞花里胡哨的理论堆砌，只分享看得懂、用得上的前端干货，

咱们一起稳步积累，真正摆脱“面向搜索引擎写代码”的尴尬。

1. 开篇：有库可用，为什么还要自己写？

lodash、ramda 等库已经提供这些工具函数，但在面试、基础补强、和「读懂库源码」的场景里，手写一遍很有价值：

• 搞清概念：什么算「深拷贝」、什么算「去重」


• 踩一遍坑：循环引用、NaN、Date、RegExp、Symbol 等


• 形成习惯：知道什么时候用浅拷贝、什么时候必须深拷贝

下面按「深拷贝 → 去重 → 扁平化」的顺序，每种都给出可直接用的实现和说明。

2. 深拷贝

2.1 浅拷贝 vs 深拷贝，怎么选？

一句话：只要会改到「嵌套对象/数组」，就考虑深拷贝。

2.2 常见坑

2.3 实现示例（含循环引用与特殊类型处理）

function deepClone(obj, cache = new WeakMap()) {

  // 1. 基本类型、null、函数 直接返回

  if (obj === null || typeof obj !== 'object') {

    return obj;

  }



  // 2. 循环引用：用 WeakMap 缓存已拷贝对象

  if (cache.has(obj)) {

    return cache.get(obj);

  }



  // 3. 特殊对象类型

  if (obj instanceof Date) return new Date(obj.getTime());

  if (obj instanceof RegExp) return new RegExp(obj.source, obj.flags);

  if (obj instanceof Map) {

    const mapCopy = new Map();

    cache.set(obj, mapCopy);

    obj.forEach((v, k) => mapCopy.set(deepClone(k, cache), deepClone(v, cache)));

    return mapCopy;

  }

  if (obj instanceof Set) {

    const setCopy = new Set();

    cache.set(obj, setCopy);

    obj.forEach(v => setCopy.add(deepClone(v, cache)));

    return setCopy;

  }



  // 4. 普通对象 / 数组

  const clone = Array.isArray(obj) ? [] : {};

  cache.set(obj, clone);



  // 包含 Symbol 作为 key

  const keys = [...Object.keys(obj), ...Object.getOwnPropertySymbols(obj)];

  keys.forEach(key => {

    clone[key] = deepClone(obj[key], cache);

  });



  return clone;

}



// 使用示例

const original = { a: 1, b: { c: 2 }, d: [3, 4] };

original.self = original; // 循环引用

const cloned = deepClone(original);

cloned.b.c = 999;

console.log(original.b.c); // 2，原对象未被修改

要点：WeakMap 解决循环引用，Date/RegExp/Map/Set 单独分支，Object.getOwnPropertySymbols 保证 Symbol key 不丢失。

3. 去重

3.1 场景与选型

3.2 几种实现

1）简单数组去重（含 NaN）

// 方式一：Set（ES6 最常用）

function uniqueBySet(arr) {

  return [...new Set(arr)];

}



// 方式二：filter + indexOf（兼容性更好，但 NaN 会出问题）

function uniqueByFilter(arr) {

  return arr.filter((item, index) => arr.indexOf(item) === index);

}



// 方式三：兼容 NaN 的版本

function unique(arr) {

  const result = [];

  const seenNaN = false; // 用 flag 标记是否已经加入过 NaN

  for (const item of arr) {

    if (item !== item) { // NaN !== NaN

      if (!seenNaN) {

        result.push(item);

        seenNaN = true; // 这里需要闭包，下面用修正版

      }

    } else if (!result.includes(item)) {

      result.push(item);

    }

  }

  return result;

}



// 修正：用变量

function uniqueWithNaN(arr) {

  const result = [];

  let hasNaN = false;

  for (const item of arr) {

    if (Number.isNaN(item)) {

      if (!hasNaN) {

        result.push(NaN);

        hasNaN = true;

      }

    } else if (!result.includes(item)) {

      result.push(item);

    }

  }

  return result;

}

注意：Set 本身对 NaN 是去重的（ES2015 规范），所以 [...new Set([1, NaN, 2, NaN])] 结果正确。需要兼容 NaN 的，多是旧环境或面试题场景。

2）对象数组按某字段去重

function uniqueByKey(arr, key) {

  const seen = new Map();

  return arr.filter(item => {

    const k = item[key];

    if (seen.has(k)) return false;

    seen.set(k, true);

    return true;

  });

}



// 使用

const users = [

  { id: 1, name: '张三' },

  { id: 2, name: '李四' },

  { id: 1, name: '张三2' }

];

console.log(uniqueByKey(users, 'id'));

// [{ id: 1, name: '张三' }, { id: 2, name: '李四' }]

4. 扁平化

4.1 场景

• 把 [1, [2, [3, 4]]] 变成 [1, 2, 3, 4]


• 有时候需要「只扁平一层」或「扁平到指定层数」

4.2 实现

1）递归全扁平

function flatten(arr) {

  const result = [];

  for (const item of arr) {

    if (Array.isArray(item)) {

      result.push(...flatten(item));

    } else {

      result.push(item);

    }

  }

  return result;

}



console.log(flatten([1, [2, [3, 4], 5]])); // [1, 2, 3, 4, 5]

2）指定深度扁平（如 Array.prototype.flat）

function flattenDepth(arr, depth = 1) {

  if (depth <= 0) return arr;



  const result = [];

  for (const item of arr) {

    if (Array.isArray(item) && depth > 0) {

      result.push(...flattenDepth(item, depth - 1));

    } else {

      result.push(item);

    }

  }

  return result;

}



console.log(flattenDepth([1, [2, [3, 4]]], 1)); // [1, 2, [3, 4]]

console.log(flattenDepth([1, [2, [3, 4]]], 2)); // [1, 2, 3, 4]

3）用 reduce 递归写法（另一种常见写法）

function flattenByReduce(arr) {

  return arr.reduce((acc, cur) => {

    return acc.concat(Array.isArray(cur) ? flattenByReduce(cur) : cur);

  }, []);

}

5. 小结：日常怎么选

自己写一遍的价值在于：搞清楚边界情况、循环引用、特殊类型，以后选库或读源码时心里有数。

学习本就是一场持久战，不需要急着一口吃成胖子。哪怕今天你只记住了一点点，这都是实打实的进步。

后续我还会继续用这种大白话、讲实战方式，带大家扫盲更多前端基础。

关注我，不迷路，咱们把那些曾经模糊的知识点，一个个彻底搞清楚。

如果你觉得这篇内容对你有帮助，不妨点赞收藏，下次写代码卡壳时，拿出来翻一翻，比搜引擎更靠谱。

我是 Eugene，你的电子学友，我们下一篇干货见～

什么是 JSBridge

JSBridge 是 WebView 中 JavaScript 与 Native 代码之间的通信桥梁。核心问题是：两个不同运行环境的代码如何互相调用？

通信原理

1. Native 调用 JS（简单）

WebView 本身就提供了执行 JS 的能力，原理很直接：WebView 控制着 JS 引擎，可以直接向其注入并执行代码。

// Android

webView.evaluateJavascript("window.appCallJS('data')", null);



// iOS

webView.evaluateJavaScript("window.appCallJS('data')")



// Flutter

webViewController.runJavaScript("window.appCallJS('data')");

2. JS 调用 Native（核心难点）

JS 运行在沙箱中，无法直接访问系统 API。有两种主流方案：