CosmoLau 的个人博客

扩展插件的开发与维护

Mon, 18 May 2026 16:44:17 GMT

Cocos Creator 扩展插件的开发与维护

本篇文章以我的开源扩展插件 batch-builder 作为案例，讲述 Cocos Creator 扩展插件在开发时如何有效的进行版本管理，并搭建一个自动化流水线来用于扩展插件的打包发布与版本检查。

说明：本篇文章未使用 AI 参与撰写与润色，作为案例的开源插件采用 99.9% 古法编码制作而成，不是瞧不起 AI，而是 AI 太贵用不起，请给我的项目点个 Star，或者在爱发电主页以及 ko-fi 让我能摆脱古法时代！

项目准备

为了降低扩展插件开发的门槛，这个项目使用 Cocos Creator 3.8.7 中提供的 Vue-Element-UI 面板 作为扩展插件模板来进行开发。大体上来说，这个模板相当于是一个比较标准的 WEB 项目。

版本管理

在对扩展插件进行版本管理时，需要分两种情况来考虑。

独立仓库

如果扩展插件需要维护统一的版本，用于多个 Cocos 项目中，那么将创建好的扩展插件项目整个初始化为 Git 项目，此时 .gitignore 中需要添加以下内容：

# npm
node_modules
# 构建产物
/dist

然后推荐将扩展插件项目转移到其他路径下，不要放在 Cocos 项目下，依次来将扩展差将与项目分开，需要进行开发时，在 Cocos Creator 编辑器中 扩展管理器 里 导入扩展文件(.zip) 旁下拉菜单，通过 开发者导入 来将整个扩展插件项目进行导入，这会在原本 Cocos 项目下的 extensions 目录中创建一个软链接用来在开发时使用。

Cocos 项目仓库

如果扩展插件就专门为这一个 Cocos 项目而开发的，那完全可以一并提交到 Cocos 的 Git 仓库中，这时就需要确认 Cocos 项目的 .gitignore 忽略文件：

# npm 必须忽略，否则会增加仓库体积
node_modules
# 可选，推荐忽略构建产物
# 第一次拉取仓库时 build 一遍即可
/extensions/${扩展插件名}/dist

注意：这里的 dist 忽略需要精确到扩展插件，避免把其他从扩展商店下载的插件给忽略了。

自动化流水线

自动化流水线主要是用于扩展插件作为独立仓库时，用来自动化构建打包与发布。

如果提交到 Cocos 项目的仓库中，一般来说只需要拉取代码后，执行一遍 build 命令即可，或者编写一个 git hooks，用来在拉取代码时，如果有扩展插件中的文件变动，自动执行一遍 build 命令，本篇文章不涉及这个内容，就不详细说明，可以直接让 AI 写一个钩子脚本。

当作为独立仓库提交时，如果提交的远端 Git 仓库支持 CI/CD，就可以编写一套自动化流水线来构建并发布扩展插件包，这里我们以 GitHub Actions 作为例子，参考 release.yml：

name: Release

permissions:
  contents: write

# 推送 v 开头的标签时触发这个 Action
on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # 检出仓库
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          # 这里 fetch-depth 设置为 0，是下面 changelog 需要
          fetch-depth: 0

      # 设置 node 环境
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          registry-url: https://registry.npmjs.org/
          # 可以更换为开发环境中使用的 node 版本
          node-version: lts/*
          cache: 'npm'

      # 安装依赖
      - name: Install dependencies
        run: npm install

      # 构建项目
      - name: Build project
        run: npm run build

      # 这里读取 package.json 中的 name 来命名压缩包
      - name: Read package name and package files
        id: meta
        run: |
          PKG_NAME=$(node -p "require('./package.json').name")
          echo "pkg_name=${PKG_NAME}" >> "$GITHUB_OUTPUT"

      # 压缩打包
      # 其中 dist、i18n、package.json 是必须的
      # 其他内容是否打包，需要根据项目情况而定
      - name: Create zip archive
        run: |
          ZIP_NAME="${{ steps.meta.outputs.pkg_name }}.zip"
          zip -r "${ZIP_NAME}" \
            dist \
            i18n \
            logo.png \
            README* \
            package.json
          echo "Created archive: ${ZIP_NAME}"

      # 发布打包后的压缩包
      - name: Upload release asset
        uses: softprops/action-gh-release@v2
        with:
          files: ${{ steps.meta.outputs.pkg_name }}.zip

      # 自动化生成 changelog
      - name: Write changelog
        run: npx changelogithub # or changelogithub@0.12 to ensure a stable result
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

在压缩打包阶段，其实核心的只有 dist 和 package.json 两个内容，其他的都可以不要，但爱看官方文档的小伙伴就会问了，在打包扩展里说：

dist、i18n、node_module、package.json、static 这几个文件（夹）为必选，缺一不可

我们这里详细盘一下：

文件（夹）	必选	说明
dist	√	扩展插件产物
i18n		如果不涉及 i18n，这是可选的
node_modules		vite 在构建时，会进行 tree shaking，需要的 npm 包实际上已经在 dist 中了
package.json	√	Cocos Creator 的扩展管理器会根据这个来运行扩展
static		这个看项目需要，如果没有用到，可以不用打包

那么代码里的 logo.png 和 README* 又是干嘛的呢？

logo.png：在扩展管理器中显示的扩展插件图标
README.zh.md：在扩展管理器中显示的资源介绍

这里吐槽一下，既然编辑器不开源，这些奇奇怪怪的规则至少也该写在文档里吧，平台支持 这一字段连官方扩展都从来没用过，不会官方自己都忘了这是怎么用的吧？

另外，流水线的最后一步是自动化编写发布时的 ChangeLog，这个需要在编写 git commit 时遵循约定式提交规范。

版本检测

如果需要做版本检测，可以使用 GitHub API 来获取 Release 中最新发布的版本号，示例插件中的版本检测就使用了这个方法来判断是否有新版本，然后通过 https://github.com/CosmoLau/batch-builder/releases/latest 来跳转最新发布页，

踩坑经验

依赖包版本

在这个扩展插件模板中，除了 vite 以外，大部分的依赖包都可以放心升级到最新版本，使用 npm install xxx@latest 升级即可。

那么为什么 vite 依赖不行呢？因为模板中使用了一个官方编写的 @cocos-fe/vite-plugin-cocos-panel vite 插件来处理打包构建的流程，但是这个 vite 插件并没有开源，而插件本身没有对 vite 新版本进行兼容性处理，所以唯独 vite 依赖不要进行升级。

node 版本

在示例项目中，会发现有个 .node-version，与 package.json 中的 engines.node 字段相同，都设置为了 20.15.1 这个 node 版本号。

这么做的目的是告诉开发者，当这个插件在 Cocos Creator 编辑器中运行时，打印 process.version 显示的版本号，也就是说 Cocos Creator 的 node 运行环境为 20.15.1。

发现这个问题是在示例项目中使用 node 内置的 fs.glob 时，发现编辑器中并不支持，这种情况就老老实实用 glob npm 包就行了。

Element-plus 的根 DOM

如果是用 Vue-Element-UI 面板 这个模板创建扩展插件项目的话，示例代码中已经提供了依赖注入，在 App.vue 中有如下代码：

<script setup lang="ts">
import { inject } from 'vue';
import { ElMessage } from 'element-plus';
import { keyAppRoot, keyMessage } from './provide-inject';

const appRootDom = inject(keyAppRoot);
const message = inject(keyMessage)!;

const open = () => {
    ElMessage({
        message: 'show message',
        appendTo: appRootDom,
    });
};

function open2() {
    message({ message: 'show inject message' });
}

</script>

<template>
    <!-- ... -->
</template>

<style scoped>
/* ... */
</style>

在 Element-plus 中的很多弹窗类组件，需要挂载到根 DOM 下才能正常显示，也就是代码中的 appRootDom，一般来说，这种类型的组件都会提供一个 append-to 属性，这个属性就是在这里使用的，例如在 el-tooltip 中使用：

<el-tooltip
    content="打开构建面板，导出构建配置" 
    :append-to="appRootDom" 
    effect="light"
    placement="bottom">
</el-tooltip>

外部链接

如果在扩展插件中使用 windows.open 方法来打开外部链接，会打开一个新的 Electron 窗口来打开。

想要解决这个方法，要么使用官方的 <ui-link> 标签，要么使用 <el-link> 标签，示例插件中用来触发 Element-plus 标签事件的方法来进行了 hack 操作：

function linkToRelease() {
    if (!canUpdate.value) return;
    // 使用 window.open 会打开一个 Electron 窗口
    // 所以这里模拟 el-link 点击来打开链接
    (githubLink.value.$el as HTMLElement).click();
}

连续构建

在扩展插件开发时，遇到过好几次构建后脚本缺失的情况，参见3.8.7 命令行连续构建，会有几次出现脚本丢失的情况这个 issue。

由于中途跟换过开发设备，感觉这个问题在低配置的机器上出现概率比较大，如果各位开发者在开发中仍然遇到这个问题，可以参考示例扩展插件中的实现：

通过 is missing or invalid 类似的日志内容来判断是否再构建时有丢失脚本。
在丢失脚本的情况下，对构建进行重试。
构建之前检查资源数据库是否准备好（query-ready 消息），这个其实也没法保证构建不会丢失脚本。

示例扩展插件简介

本篇文章的示例扩展插件已开源，详细说明可以到 batch-builder 仓库和插件资源介绍中查看，这里只做简单介绍。

batch-builder 是一个批量构建项目的插件，由于项目需求，Cocos Creator 中的每个 .scene 场景文件都作为一个单独的项目进行打包构建，其数量在几十个左右，未来可能会更多。在这种情况下，如果要使用 Cocos 的构建面板，每个项目都需要单独勾选场景和 bundle，在场景文件数量非常多时，这是非常低效且容易犯错的重复工作，所以本扩展插件应运而生。

为了减小项目体积，每个场景文件专属的资源会放在同名的 bundle 包下，而整个项目共用的资源会放在 resources 目录下，做好这个约定后，才能统一构建流程。

这个扩展插件的构建方式是基于命令行的，这样才能对构建配置进行高度自定义，所以这里有个可以优化的点，在使用这个扩展插件时，需要先在 构建面板 中对任意一个项目进行一次正常构建，构建成功后将构建配置文件进行导出，以供扩展插件使用。

通过 扩展 -> 批量构建工具 🛠️ 打开扩展的面板后，填入所需内容，就可以在 项目列表 里多选需要批量构建的场景文件，然后点击构建即可。

结语

这篇文章和这个插件如果再不发布，等 PinK IDE 和 Cocos-cli 正式上线，就要过时了:cry:。为了证明在 Creator 时期待过，以此为纪念。

我相信 AI 应该能轻松复刻这个扩展插件，但是 Cocos 在 Creator 时期，文档别说是 AI 不友好了，甚至是“人类不友好”，希望 Cocos 能在 SUD 接手下，有个体面的结局未来。

2025 年终总结

Fri, 19 Dec 2025 00:00:00 GMT

2025 年终总结

从今年开始，如果没什么大变故的话，打算坚持每年年底写一个年终总结，记录一下今年的生活、发现的有趣项目、学到的新知识，亦或是谈谈自己的想法之类的，内容可能会比较庞杂混乱，所以主要还是作为记录留档。

站点建设

目前呈现本篇内容的站点是一个博客站点，我将其解析到了 blog.cosmolau.top 这个三级域名下，并将其存储在 GitHub 仓库中，通过 GitHub Pages 进行部署。

::github{repo="CosmoLau/blog"}

但其实现在 www.cosmolau.top 站点也是一个博客站点，这个站点是我一开始部署站点，后面我将其迁移到 blog.cosmolau.top 这个三级域名下，并做了些许的个性化更改。

<www.cosmolau.top> 站点的内容是存储在 https://github.com/CosmoLau/site 仓库里，他是用 Hexo 搭建的博客，使用的 Vivid 作为博客主题。因为 Vivid 的作者不再维护这个 Hexo 的主题，转投到了基于 Astro 的 Fuwari 项目上，所以我也跟着对博客进行了迁移（就是本篇内容呈现的样子）。

::github{repo="CosmoLau/site"}

当时在考虑迁移博客的时候，我进行了一个简单的规划，我认为 www.cosmolau.top 或者说 cosmolau.top 这个域名不应该用来展示我的博客内容，而应该作为我个人的作品集展示页面，这样才能更好的 showcase，不过羞于至今为止都没有什么拿得出手的项目，所以到现在也没能对作品集页面进行装修。

基于以上想法，对作品集页面的装修工作将作为我 2026 年的目标之一，我希望这个作品集页面不光作为一个自我介绍的页面，也能见证我在技术上的成长，让我的目标更加清晰。

生活与工作

基于各种原因，我从 2023 年 10 月就开始在家啃老，一直到 2025 年 8 月才总算找到了工作，不论如何，也算是重新走上了正轨吧。

在家里呆着的这 2 年，其实整个人也是非常煎熬的，每天没有事情干，程序也不想写，只能颓废地打游戏。对于一个普通人来说，梦想真的是奢望，没有经济也没有坚定的信念，就只是空谈，一场幻想罢了。

作为一个从小喜欢玩游戏的重度玩家，到初入职场进入游戏开发行业，我仍然想要做出一款自己的游戏，但至今一事无成。信念啊，金钱啊，时间啊，都是我的借口，一直都只是在逃避，没有真正迈出这一步。但是今年借助 AI 的辅助，真让我成功开发了两个总算看得过去的 DEMO，我认为这是个好兆头，也许我之前连一个 DEMO 都做不出来的原因，就是缺一个全能型的开发搭子。我让 AI 帮我写测试用的数值，帮我分析策划案，真的能让我事半功倍，也比以往更有兴致，觉得至少我想的玩法有个明确的开发方向了。

2026 年，希望能把现在的工作稳住，然后在 AI 的加持下，完成一款能达到上架水准的完整游戏。

年度新物

今年开始，我会记录一些新发现的、不错的、甚至已经替换进我的工作流中的应用、网站、软件、硬件或者其他什么的。

笔记✍🏻

在笔记这方面，我因为在第一份工作结束时，忘记备份笔记，所以在这方面非常懊悔。从那时起，我在 GitHub 上建了一个名为 MyNote 的仓库来管理我所有的笔记。因为我现在都是用 VSCode 作为编辑器来写 Markdown，所以这一套流程还算是比较方便，甚至在今年折腾的过程中，发现可以在 vscode.dev 上非常丝滑的拉取 GitHub 仓库并修改推送，满足了跨平台笔记编写的需求，唯一的缺点就是在手机上访问 vscode.dev，会显得非常的局促，不过用来应急完全是够用的。

当然，我也在寻找一些其他的笔记方案，目前让我比较满意的一个方案就是 Notion。Notion 可以说是功能非常强大的一个笔记应用了，也支持几乎所有平台（包括在 web 上直接访问），我想不出有什么很致命的缺点，可能国内访问不太稳定算一个缺点吧，还有在我的小米平板7S Pro 上识别键盘有点问题，不过这个已经修复了，虽然不知道是软件的原因还是硬件的原因导致的。

Git 客户端

我在大学时没怎么使用 Git，当开始工作时，Git 成为了必要工具，而我一开始接触到的就是带有图形化界面的 Git 客户端 SourceTree。

说实话，SourceTree 让我又爱又恨，它几乎是陪伴我至今的 Git 客户端，但其在 Windows 上的性能很差劲。直到我在 V2EX 上看到一篇讨论 Git 客户端的贴子，评论区有人推荐了国人开发的开源 Git 客户端 SourceGit，才让我彻底抛弃陪伴已久的 SourceTree。

::github{repo="sourcegit-scm/sourcegit"}

当然，这篇贴子中提到的几款 Git 客户端产品我也有用过，但我体验下来后的感觉是：

Git 客户端	感受
ugit	腾讯系，内置一大堆我用不到的功能，太臃肿
fork	非常好，但是不支持多语言，我有多语言强迫症
GitKraken	收费，不考虑
tortoise git	疯狂原始龟
github desktop	也是不支持多语言

所以基于体验后的感受，最后选择了 SourceGit，应该至少会长期使用一段时间，不过在最近的使用中，已经发现一个 BUG，问题倒不是很严重，就是当文件只读时，无法提交，已经在相关 issue 中回复了，希望 BUG 都能今早修复吧。

当然，没有使用 Git 客户端的习惯的话，直接使用 IDE 自带的 Git 也能满足基本需求。

数码产品

今年终于找到工作了，有收入来源了，终于可以消费了，还是列个表格来讲自己至今的感受，表格按照购入顺序排序：

产品	感受
小米平板7S Pro	小米自研玄戒O1 CPU，感觉性能还是差了点，很多游戏甚至跑不到 60 帧，还是说平板都这样？不过看视频是真爽
iPhone17	有史以来最值得升级的一代，立刻换下我的 iPhone 11，高刷快充（？）无需多言
机械革命星耀14	1.05KG 轻薄本，目前我已经找好笔记本电脑的定位，一定要轻，打游戏就应该在台式机上去享受大屏幕，而不是笔记本
AirPodsPro 3	我的第一个无线耳机，延迟挺高不适合游戏使用，其他场景基本没啥问题，也说不上好坏吧，毕竟我也没用过别的无线耳机

家里有一台 2016 年上大学时买的 i5 6300hq + GTX960M 的笔记本电脑，现在运行 Windows 10 都有点费劲，最近有看到不少人开始使用 Linux Desktop，我也萌生了这样的想法，有时间给这台老笔记本电脑装个 Linux，看能不能焕发第二春。

AI

今年应该说 AI 非常火热，各种神仙打架，但是我基于不想折腾网络的原因，所以在 AI 使用方面比较保守，代码编辑器用的字节家的 Trae，信息检查还是用的 DeepSeek，感觉要让我走上 AI 付费的道路，还得看我经济积累得如何，目前感觉能用就行。

技术栈

我之前有想过做一个记录自己技术掌握程度的应用，但是在做成之前，roadmap.sh 是我觉得很不错的一个替代产品，我目前时不时都会在上面更新一下我的掌握情况。

由于今年重新开始参加工作的原因，我算是强行把一些以前想学习的技术栈落实了下来：

Vue：业务需求要做 uniapp，要用到 Vue2，做 Cocos Creator 的扩展开发会用到 Vue3，以前认为 Vue 用着没什么难点，直到那个奇怪的响应式对象引用搞的我有点头大，这就是一部分人说 Vue 是黑魔法的原因吗？
React：React 也有想吐槽的地方，返回的 HTML 代码块如果需要处理逻辑判断，会显得非常的乱，这点可能没 Vue 的代码和样式分离来的清晰，但是在 JS/TS 代码编写这块，感觉还是更本源一点，暂时没有遇到 Vue 中类似的一些坑。
Elysia.js：我现在基本上都是使用 bun 作为包管理器，也借此了解到 Elysia.js 这个后端框架，之前用过 express、koa 之类的，我感觉使用起来也都没啥差别吧，既然 Elysia.js 说自己性能强，那我就索性一步到位了。然后不出意外的话，就出意外了，他的静态插件不知道是什么原因，打开静态目录下的文件超过一定数量就会有缺失了，后面还是把这一块的工作交给了 Vite 来完成。
uniapp：如上面所说，业务需要，然后用了之后硬生生给我干成工伤。如果没有跨平台小程序需求，我觉得我应该永远不会使用 uniapp 来开发程序，强绑 HBuilderX 太让人难受了，我现在都是开发用 VSCode 来做，预览打包才在 HBuilder 上进行，甚至预览也不如浏览器上直接预览，DCloud 别抱着你那 HBuilderX 了，拥抱 VSCode 生态不好吗？现在的 AI 编辑器也都是用 VSCode 改的了。

当然还有我最爱的本职技术栈 Cocos，在我觉得他马上要死的时候，他被 SUD 以 5 亿人民币收购了，近期也是规划了 PinK AI 编辑器 和 Cocos Creator 4.x，那我还能说什么呢，能不能拳打 LayaBox、Godot，脚踢 Unity、Unreal，Make Cocos Great Again！

结语

总之，2025 年马上要过去了，后面日子希望我真的能踏上正轨，我还有很多想做的事没做，想学的东西没学，不求大富大贵，但求个稳定吧。

也在此督促一下自己，明年记得也要写一篇年终总结。

在安卓平板上编写代码

Wed, 27 Aug 2025 00:00:00 GMT

在安卓平板上编写代码

生产力？伪命题？平板电脑真能敲代码吗？

前言

时隔两年总算找到份自己觉得合适的工作，不过出门工作，就得和家里亲手 DIY 的台式机告别了，虽然还有一台笔记本电脑可以凑合，但是它 2016 年的性能已经被我唾弃了。于是乎在考虑入手下一台笔记本电脑之前，我准备先买一个平板电脑过度，这也让 5 年没接触过安卓设备的我重新认识一下现在的安卓，就这样入手了一部小米平板7S Pro作为我现在少有“生产力工具”。

都说平板电脑拿来当“生产力工具”是伪命题，那么当你看到本篇文章被发布时，至少说明了平板电脑在写代码这一块，还是有那么一丢丢的生产力的。

准备工作

首先需要说明一下，我本职工作是游戏开发，但是一般的游戏开发都会使用到游戏引擎，而大部分游戏引擎应该只有 Windows 和 MacOS 应用，而且开发过程比较复杂，所以游戏开发其实并不是本篇文章的目的。

而我另一个兴趣，就是 TypeScript 全栈开发，对于 Web APP 的跨平台性而言，应该在任何设备上进行都不在话下。在此之前，需要确认一下我们的需求：

手上有一个平板电脑，且最好配备蓝牙鼠键（至少也得有个键盘）
有前后端的开发需求
使用 VScode 作为主力编辑器
使用 GitHub 作为主力存储仓库

如果满足以上需求，那么接下来的内容应该非常适合你。

vscode.dev——代餐

如果你的需求相比上面的更简单，仅仅只是想编辑一下 GitHub 仓库里的代码，那么使用 <vscode.dev> 这个网页版的 VScode 其实就能满足需求了，而且它能登录微软账户，同步你的 VScode 配置，保证你的插件生态体验，

但是网页版 VScode 唯一的缺点就是没有终端，不过想来也是，微软也不会白白送一个开发环境。

但是即使如此，你如果有一个配置好 CI/CD 的博客仓库，需要更新博客文章，那么 <vscode.dev> 几乎是完美的代餐。

Termux——Android Subsystem for Linux

提到安卓设备上编写代码，那么肯定绕不快 Linux 环境的搭建，只要上网一搜，Termux 肯定是首选方案，甚至没有之一。

推荐在 F-Droid 商店下载 Termux 最新版。

下载好 Termux 后，当然就是搭建一个完整的 Linux 环境。

# 更新 Termux 的包管理器
pkg update
pkg upgrade
# 如果无法下载，可能需要更换源
termux-change-repo
# 如果要访问存储，需要申请权限
termux-setup-storage
# 安装 proot
pkg install proot-distro
# 查看可安装的 Linux 系统
proot-distro list
# 安装自己熟悉的 Linux 系统，我这里使用 ubuntu
proot-distro install ubuntu
# 登录 ubuntu
proot-distro login ubuntu

根据以上步骤，环境就算是搭建完成了，可能还需要在设置里打开开发者模式（连点系统版本号），然后在设置里搜索 停止限制子进程 并打开此选项。

code-server——启动

Termux 安装好 Linux 环境后，就是搭建开发环境了。

# 确保使用 proot-distro login ubuntu 进入 Linux 系统

# 安装 code-server
curl -fsSL https://code-server.dev/install.sh | sh
# 查看 code-server 版本号，确认是否安装成功
code-server --version
# 查看并复制 code-server 密码
cat /root/.config/code-server/config.yml
# 其中 password 就是我们等会需要使用的密码
# 启动 code-server 服务
code-server

完成以上操作后，就可以打开浏览器，访问 127.0.0.1:8080 使用 VScode 了。

这个 VScode 是有终端可以使用的，但是不能同步微软账号，插件系统中的插件也不一定能运行（可能是缺少环境）。

编码环境

因为我是做 TypeScript 全栈开发，那么 Node 环境是必备的，我习惯起手安装 nvm，到 nvm 官方仓库找到安装脚本运行即可：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

这里需要注意一下，安装完成后可能需要重启 linux，我们使用 exit 命令退出到 Termux 后重新登录即可。

# 退出 linux
exit
# 重新登录
proot-distro login ubuntu
# 然后就可以使用 nvm 了
nvm -v

安装好 Node 环境后，在安装一个 Bun 来运行 Elysiajs 后端框架

# 安装 Bun
curl -fsSL https://bun.sh/install | bash
# 安装完成后同样用重启 linux
exit
proot-distro login ubuntu
# 创建一个文件夹用来存放工程
mkdir workspace
cd workspace
# 生成一个 Elysiajs 项目
bun create elysia app
cd app
bun run dev

完成后在浏览器中新建标签页，访问 localhost:3000 即可看到 Hello Elysia 啦。

其他说明

如果按照以上步骤跟下来，使用 bun create astro app 或者 bun create vue app 之类的命令来初始化框架可能会遇到报错，这些大概率都是缺少其他环境导致的，只需要把报错扔给 AI，让 AI 帮你解决即可。

后记

至此，本篇文章结束，如果对你有帮助的话，世界上也会少一个沦为泡面压的平板电脑，如果当你看到这篇文章出现在博客，那么我可以很高兴的告诉你，本篇文章的更新来自我的 小米平板7S Pro。

Windows 11 安装相关备忘录

Tue, 12 Nov 2024 00:00:00 GMT

安装系统应该算是一个不太频繁，但又很必要的操作，恰恰就是其频率不高，导致每次遇到的时候总会忘记一些之前踩过的坑，所以便有了本章作为一个踩坑备忘录。

情景

试想一下，一般需要安装 Windows 11 系统是在哪些情况下？就我个人而言，应该有以下几种情况：

mindmap
    root(安装 Windows 11)
        购入新电脑
        电脑故障
        入职新公司

其实主要就是 新装系统 和 重装系统 两种情况，两者的区别不大，但是 重装系统 可能多一些坑，我在下文会提到。

备忘

这部分我会按照先后顺序来记录。

事前准备

如果是 购入新电脑 的情况，对于 笔记本电脑 来说，一般来说不太需要什么准备，电脑生产厂商应该会给你预装 Windows 11 系统。唯一需要注意的就是从开箱到开机的全程录屏，需要确保是首次激活，以免遇到 “二手电脑”。如何判断是不是首次激活，可以善用搜索引擎或者到各大视频平台搜索相关视频。

如果是 入职新公司，那情况就各种各样了，有可能老板给你配了个新电脑，也有可能给你上个离职员工用过的设备，如果是新购置的笔记本电脑，同上。如果是上个员工用过的电脑，你可能需要重装，这种情况最简单的办法就是去微软官网下载一个 ISO 系统镜像来安装，或者直接在 Windows 设置里重置电脑，简单快捷，无需多言。

那么，当你遇到 电脑故障 或者 新买的台式机，那你可能需要先做一个 PE 系统盘来辅助安装，我一般使用 WEPE 来制作 PE 系统盘，这需要先准备一个 U 盘，然后找个能用的电脑来制作，PE 系统盘是让你在没有安装系统时，通过 U 盘来启动一个非常小的系统，方便来安装新的 Windows 系统，也就是说，这个 U 盘制作完成后，同样也需要一份 ISO 系统镜像放入 U 盘里才能安装。

:::tip 如果你像我一样很久以前就有一个 PE 系统盘，那么你可能需要重新制作一个新的 PE 系统，因为以前的 PE 系统不一定能打开 Windows 11 安装镜像。 :::

安装引导

到成功安装系统，或是在启动新购入的笔记本电脑时，会进入到 Windows 11 的安装引导中，如果在联网情况下，引导应该会让你登录微软账号来作为 Windows 用户，但可能对一部分人来说，微软账号的昵称是中文的（可能用的真实姓名，比如我），这会导致用户文件夹也是中文，对某些软件来说，中文文件夹会导致无法读取（大概是软件使用的编码格式导致的）。所以，要么断网使用本地用户，要么就进入系统之后重新创建一个用户。

修改用户名

如果你没法在安装引导使用本地用户登录，那么我这里有一个方便快捷的修改用户名方法，不需要修改注册表。

首先在 设置 -> 账户 -> 添加账户 中新增一个账户，在弹窗中选择 我没有这个人的登录信息，后面再选择 添加一个没有 Microsoft 帐户的用户，这样就能创建一个本地用户了。添加完成后，记得给本地用户设置为管理员。

然后在 账户 -> 你的信息 中找到 Microsoft 账号，点击 改用本地账户登录，这样就成功将当前账户的微软账号退出了。

接着注销，切换到刚才新建的用户，此时这个新建的用户的用户文件夹就不是中文了，只需要在账户中找到那个中文的用户删除掉就行，如果不在上一步退出微软账号，这一步就没法删除中文用户了。

无密码登录

可能有部分家用台式的人有这个需求，就是不想要设置密码，除了在上个步骤中新增本地用户时不设置账号外，还需要一个操作，使用 <kbd>Win</kbd> + <kbd>R</kbd> 快捷键打开运行窗口，输入以下内容：

netplwiz

确定后打开窗口，在窗口中将 要使用本计算机，用户必须输入用户名和密码 取消勾选，这样才能在每次开机时不再输入密码。取消勾选时会让你确认密码，其实就是每次自动给你登录了。取消勾选后记得 应用。

本地 Git 仓库

如果你是 重装电脑，本地有一些 Git 仓库，那么可能会无法使用这些仓库，需要在 git bash 中输入

git config --global --add safe.directory "*"

用这个配置来解决无法使用本地 Git 仓库的问题。

驱动相关

下载 AMD 驱动时，千万别下载 StoreMI 这个驱动，这个确定已经停止维护，他会导致硬盘盘符相互替换，然后开机无限蓝屏。

如果手贱不小心下载了这个驱动，那么就用 PE 系统中的 DISM++ 里找到驱动管理，然后找到 存储控制器，把 Advanced Micro Devices, Inc 整个勾选上然后删除，盘符使用分区工具重新指派即可。

BIOS 相关

承接上文，我就是那个手贱下载 StoreMI 的，以为 CPU 炸了导致的蓝屏 BAD_POOL_CALLER，外加我电脑平时也经常蓝屏，以为是 CPU 电压的问题，结果在 BIOS 中改了 CPU 电压和内存条电压，这个电脑直接没法点亮了。

如果是这种情况，一般主板都有重置的方法，以我的微星 B450m Mortal Max 迫击炮为例，在主板左下角的音频针脚上方有两个 JBAT1 针脚（具体查看主板说明书），将其短接 5 - 10 秒即可重置 BIOS 设置，不同主板的方法肯定不同，不过应该都能在说明书上找到。

站点记录

Fri, 01 Nov 2024 00:00:00 GMT

timeline
    title 站点重要时间线
    2022.10.18 : 部署 Hexo 博客站点
    2024.4.1 : 使用 vivia 主题
    2024.10.31 : 使用 Fuwari 主题

2024.10.31

我刚用上 vivia 作为主题不久，作者就停止了维护，转而投入到 Fuwari 的开发。由于 Fuwari 是基于 Astro 的，我又不太想换一个不熟悉的框架，而且 Fuwari 还有些问题不符合我的预期，所以迟迟没迁移。

直到这天，Fuwari 已经基本符合我的预期，我也对站点进行了一次小小的规划，将其部署到了 blog.cosmolau.top 这个域名上。

::github{repo="saicaca/fuwari"}

2024.5.20

这天我翻译的 Husky 文档终于被合并了，起因是我想把我的 husky 分叉仓库部署到自己的域名上，结果在添加了 CNAME 文件后，发现 PR 也被同步修改了，此时我才发现，原来提交 PR 的流程我还是没搞懂。

::github{repo="CosmoLau/husky"}

我将构建后的文档部署到了 www.cosmolau.top/husky/zh/，不过现在我还是建议你去看官方文档。（顺便说一下，官方文档的多语言支持也是我做的）

2024.4.16

将 oclif 文档翻译成了中文，并添加了多语言的支持，不过提交的 PR 并没有被采纳。

::github{repo="CosmoLau/oclif.github.io"}

既然官方没法合并 PR，那我就只能自己部署在 www.cosmolau.top/docs/oclif/zh/ 了。

2024.4.1

博客长期没有维护，我觉得可能是我选的主题不符合我的审美，所以到 Hexo 官方收录的主题页寻找自己对的上眼的主题，最终选择了 vivia。

::github{repo="saicaca/hexo-theme-vivia"}

作为新博客的第一天，我把我发布在 Cocos 论坛的文章做为了本博客的第一篇文章，《【从零开始的插件开发】使用 CC3.x + UI组件 + Vue3 开发一个插件》发布了。

2022.10.18

因为看见别人的 Demo 域名为 github.io 后缀，所以知道了 GitHub Pages 的存在，然后在一众静态博客框架中选择了 Hexo，其原因是 Hexo 是 JavaScript 写的。

我正好有个域名，索性就把 GitHub Pages 修改成了自定义域名 www.cosmolau.top。

使用 Docker 快速搭建《我的世界》（Minecraft）服务器

Wed, 15 May 2024 13:29:50 GMT

本篇是一个使用 Docker 进行游戏服务器快速搭建的教程，需要先自行安装 Docker，以做好前置准备。

本教程基于 docker-minecraft-server 项目进行部署，详情请参阅 docker-minecraft-server 文档。

快速部署

docker run -d -it --name mc -p 25565:25565 -e EULA=TRUE -v /home/minecraft/data:/data itzg/minecraft-server

--name mc：设置容器名，此处设置为 mc，方便下文使用。

-v /home/minecraft/data:/data：将容器数据卷挂载到 /home/minecraft/data 路径下，可自行修改，此处方便下文使用。

执行以上命令后，等待 docker 部署完成，最基础的 Minecraft 服务器就已经搭建成功了，此时已经可以尝试通过 Minecraft 的 多人游戏 连接到服务器公网 IP 了。

注意：如果使用家庭网络搭建服务器，一般是没有 IPv4 的公网 IP 的，可以尝试使用 IPv6 来连接。部分云服务商还需要手动开启对应的端口访问，比如我使用的阿里云服务器，需要到安全组中放行上面命令行用到的 25565 端口即可。

修改服务器参数

服务器搭建完成后，如果需要修改参数，就要找到 Minecraft 服务器对应的 Docker 数据卷（volume）挂载的路径。如果使用了上文的快速部署命令，路径应该为 /home/minecraft/data，切换到改路径下：

cd /home/minecraft/data

找到路径下的 server.properties 文件，内容大致如下：

#Minecraft server properties
#Wed May 15 05:00:42 UTC 2024
accepts-transfers=false
allow-flight=false
allow-nether=true
broadcast-console-to-ops=true
broadcast-rcon-to-ops=true
difficulty=easy
enable-command-block=false
enable-jmx-monitoring=false
enable-query=false
enable-rcon=false
enable-status=true
enforce-secure-profile=true
enforce-whitelist=false
entity-broadcast-range-percentage=100
force-gamemode=false
function-permission-level=2
gamemode=survival
generate-structures=true
generator-settings={}
hardcore=false
hide-online-players=false
initial-disabled-packs=
initial-enabled-packs=vanilla
level-name=world
level-seed=
level-type=minecraft\:normal
log-ips=true
max-chained-neighbor-updates=1000000
max-players=20
max-tick-time=60000
max-world-size=29999984
motd=A Minecraft Server
network-compression-threshold=256
online-mode=true
op-permission-level=4
player-idle-timeout=0
prevent-proxy-connections=false
pvp=true
query.port=25565
rate-limit=0
rcon.password=
rcon.port=25575
region-file-compression=deflate
require-resource-pack=false
resource-pack=
resource-pack-id=
resource-pack-prompt=
resource-pack-sha1=
server-ip=
server-port=25565
simulation-distance=10
spawn-animals=true
spawn-monsters=true
spawn-npcs=true
spawn-protection=16
sync-chunk-writes=true
text-filtering-config=
use-native-transport=true
view-distance=10
white-list=false

参数对应的功能可以在 Minecraft WIKI 中查看，按需修改对应的参数即可。

修改完成后，需要重启一下 Docker 容器，参考下文 Docker 常用命令。

常用参数

如果不想一个一个查看参数对应的内容，我这里会给出一些常用的参数配置说明，以便快速修改。

# 游戏难度
# peaceful - 和平
# easy - 简单
# normal - 普通
# hard - 困难
difficulty=easy

# 游戏模式
# survival - 生存模式
# creative - 创造模式
# adventure - 冒险模式
# spectator - 旁观模式
gamemode=survival

# 最大玩家数
max-players=20

# 队友伤害
# true - 玩家可以互相伤害。
# false - 玩家无法互相造成伤害（也称作玩家对战环境（PvE））。
pvp=true

# 启用白名单
# false - 不使用白名单。
# true - 从 whitelist.json 文件加载白名单，需要在 whitelist.json 中添加玩家的用户名，对应的玩家才能加入服务器。
white-list=false

Docker 常用命令

查看所有 docker 容器：

docker ps -a
# 输出内容如下
CONTAINER ID   IMAGE                        COMMAND                   CREATED        STATUS                       PORTS                                           NAMES
19bb186f2584   itzg/minecraft-server        "/start"                  16 hours ago   Up About an hour (healthy)   0.0.0.0:25565->25565/tcp, :::25565->25565/tcp   mc

重启 Docker 容器：

# 使用容器名来重启，例如容器名为 mc
docker restart mc
# 如果容器名太长，也可以使用容器 ID（CONTAINER ID），输入 ID 前几位即可
docker restart 19bb1

暂停 Docker 容器：

docker stop mc

启动 Docker 容器：

docker start mc

踩坑分享

设置了一次白名单之后，如果重启一次容器，可能导致白名单的用户无法进入服务器，具体原因未知，所以我直接关闭了白名单，这种情况请注意保护好自己的公网 IP 不要泄露，否则可能有其他人捣乱。

如果遇到 暂时无法连接到登录验证服务器，请稍后再试，检查一下是否修改过本机的 hosts，如果有修改，清理一遍重进就行。

服务器建议 4G 内存起步，2G 很容易炸掉，不推荐用来部署 Minecraft 服务器。

参考

Docker docker-minecraft-server docker-minecraft-server 文档 Minecraft WIKI

使用 VitePress 移植 Cocos 文档

Thu, 04 Apr 2024 15:04:23 GMT

原文链接：https://forum.cocos.org/t/topic/150946 <br> 注：官方文档已移植为 VitePress 版本，参阅Cocos Creator 用户手册

众所周知，Cocos 文档是使用 GitBook 发布的，如今已经有了更多成熟的静态网站生成器来构建个性化的开发文档，那么 Cocos 文档是不是也能换件新衣服呢？

正巧最近在学 Vue3 的时候，发现 Vue3 是由 VitePress 构建的，作为出名的前端技术团队维护的静态站点生成器，想必有其特别之处，跑去看了下 VitePress 开发文档，没想到上手如此的简单快捷，就萌生了移植 Cocos 文档的想法。

先上效果图：

如果觉得效果还不错，可以到 https://www.cosmolau.top/docs/cocos/ 在线体验一下，由于移植的工作量主要在于侧边栏的移植，目前 500 多篇文章只有 100 多篇显示在了侧边栏，这还只是中文文档（英文文档也是 500 篇），所以在线版的并不完整。感兴趣的话可以到 GitHub 仓库来参与移植，或者 fork 下来自己把玩也行。

自动化移植

手动移植是最笨的方法，而且非常消磨精力，所以就得考虑下自动化移植。

移植主要的内容是侧边栏，GitBook 的侧边栏目录写在一个 Markdown 文件中，想要自动化移植，可以使用 mdast-util-from-markdown Nodejs 库来读取 Markdown 的抽象语法树，然后再生成一份对应的 JSON 格式目录配置，粘贴到 VitePress 项目的 config.ts 中就行了。

限于我本人能力太菜，精力有限，这个课题就交给感兴趣的同学去研究吧。

VitePress 移植踩坑

如果你想了解更多，下面我会分享我在移植过程中遇到的各种坑。

img 标签路径错误

在 Cocos 官方文档中，相当部分的图片使用了 img 标签来引入，例如：

# 使用 JSB 手动绑定

...

<a href="jsb/infrastructure.png"><img src="jsb/infrastructure.png" alt=" "></a>

<div style="text-align:center"><p>新版 ABCmouse 的应用架构：基于 callStaticMethod 与 evalString 进行通信</p></div>

这个 Markdown 文件在开发时不会报错，但是在构建时就会报如下的错误：

build error:

Error: [vite]: Rollup failed to resolve import "jsb/infrastructure.png" from "E:/myWorkSpace/docs/docs/zh/manual/advanced-topics/jsb-manual-binding.md".

This is most likely unintended because it can break your application at runtime.

If you do want to externalize this module explicitly add it to

build.rollupOptions.external

这个报错困扰了我很久，在 VitePress 的 GitHub 仓库的 issue 中也没能找到解决方案。最终发现是因为引用的路径有误，正确的路径应该加上 “./”，做法如下：

<a href="./jsb/infrastructure.png"><img src="./jsb/infrastructure.png" alt=" "></a>

巧用 VSCode 的搜索功能来批量替换。

丢失终止标签

Element is missing end tag

有些标签是需要成对的，会有一个形如 </> 的终止标签，如果遇到这个报错，就得看看是不是哪个标签少了个 /。

错误的扩展名

cocos-docs 中部分图片使用的大写字母 .PNG 结尾，这也会使 VitePress 在构建时报错，修改成小写 .png 即可，图片的扩展名也需要改成小写 .png。（这个问题不是 BUG，具体参考这个 issue）

还有几个报错，相对这几个都是小问题，可以去 VitePress 上搜相关的 issue，不过还是吐槽一句，终归还是部分 Markdown 文档不够规范。

结尾

最近看到 Dashboard 马上要翻新了，手册文档是不是也该翻新一下，新瓶装旧酒。文档虽然还有进步空间，但看着舒服也算能赢一半吧（狗头）。

【从零开始的插件开发】使用 CC3.x + UI组件 + Vue3 开发一个插件

Mon, 01 Apr 2024 18:40:44 GMT

视频教程 <iframe src="//player.bilibili.com/player.html?aid=357514260&bvid=BV1VX4y1t7tH&cid=1170026892&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" width="100%" height="400px"></iframe>

前言

近期发布了一个 Cocos Creator 2.4.x 的自动化插件，想移植到 3.x 版本，但扩展编辑器官方文档的教程让我这种小白一言难尽，尽管我刚开发完一款 2.x 的插件，3.x 也让我折腾了很久。

首先得吐槽一下插件开发的官方文档，感觉不如 2.x 的文档，特别是 UI 组件文档，感觉像是随便写的，虽然可以直接在 UI 组件面板 中看到代码，但示例代码也有很多坑。而扩展改名这篇文档更是重量级，真的会有人需要用到这篇文档吗？不过还是叠个甲，希望只是官方没有太多精力去维护插件开发的文档。

那么废话就到此为止，本篇文章算是个技术总结，毕竟我也算是从零开始开发的插件，踩了许多坑，虽然没啥技术力，但入门应该是够了。下面将一步一步教大家通过 CC3.x + UI组件 + Vue3 的形式开发一个简单的可视化插件。

为何选择 Vue3 模板开发？

Cocos Creator 3.x 支持创建 HTML 面板、Vue2.x 面板、Vue3.x 面板，对于有对应技术栈的开发者来说，选择对口的模板是最好的选择。但如果是一位平时只使用 Cocos Creator，不太接触其他框架的小白来说（比如我），不妨选择最新的技术栈，这样能通过学习插件开发的同时，了解下 Vue3 的基础概念（~~如果以后不做 Cocos 了，方便快速转行~~）。

当然，我也是一个 Vue3 入门的新手，对 Vue3 理解不够透彻，文章中会大量引用 Vue3 官方文档的内容来进行解释，同时也引用了大量的扩展编辑器官方文档来解释，本篇文章只能算是官方文档的补充说明。（~~并不是真的教官方写文档~~）

创建扩展

首先我们通过扩展模板与编译构建文档中的方法来创建一个 Vue3.x 面板 扩展，我们将 扩展名 改为 extension-vue，方便后面讲解。

创建完成后，在项目工程的 extensions 文件夹中会生成这么一个目录结构：

目录结构的详细解释，在目录结构中有记载，包括 package.json 的字段含义，也在同一篇文档中。

此时已经创建好了一个扩展模板，需要按照 README.zh-CN.md 中的方法来安装 npm 依赖。

注意：使用 npm 需要安装 Nodejs 环境，如果你还没有安装，推荐 Windows 开发者安装 NVM for Windows 方便进行 Nodejs 的版本管理。（~~总有一天会需要用到切换版本的功能~~）

安装 npm 依赖 需要打开终端来执行命令，如果你对终端的用法不了解，可以在 VSCode 中使用快捷键 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>`</kbd> 来打开，然后以此执行以下命令：

# 切换到扩展目录下
cd .\extensions\extension-vue\
# 安装 npm 依赖
npm install

然后我们回到 Cocos Creator 编辑器，在 扩展 -> 扩展管理器 -> 已安装扩展 中启用创建好的扩展。

提示：在开发插件的过程中如果遇到数据没刷新之类的问题，可以使用此方法来重新关闭开启插件，以重新加载插件。

接着就能通过 面板 -> extension-vue -> 默认面板 打开扩展模板面板，此时已经完成了扩展的创建。

使用 UI 组件布局

面板布局主要在 extension-vue/static/template/default/index.html 中进行修改，下面统一用 index.html 来代指。

如果需要添加 CSS 样式，可以在 extension-vue/static/style/default/index.css 中进行添加，下面统一用 index.css 来代指。

我们根据 UI 组件文档的步骤，通过 开发者 -> UI 组件 来打开 UI 组件面板，这个面板里的参考代码很重要（也有很多坑），我们整个开发过程中都会用到，可以一直开着这个面板。

我们回到 index.html 中，我们先将 <my-counter></my-counter> 和 <h1 id="text"></h1> 注释掉，接下来要添加的所有 UI 组件标签都需要写在 <div id="app"></div> 标签内。

接下来我们尝试用 UI 组件拼出一个界面来。

使用 ui-prop 组件

ui-prop 组件能让可视化界面有一个整洁的排版，是很适合用来设置布局的组件。

我们先来看一下 UI 组件面板中的 layout -> ui-prop 组件示例：

先将第一个示例添加到 index.html 的 app 标签中，并且添加一个 <h1></h1> 标签来作为面板的标题。

<div>
    <div id="app">
        <!-- 所有 UI 组件写在 <div id="app"></div> 标签内 -->

        <h1>Extension Vue</h1>

        <ui-prop>
            <ui-label slot="label">Checkbox</ui-label>
            <ui-checkbox slot="content"></ui-checkbox>
        </ui-prop>
        
        <ui-prop>
            <ui-label slot="label">Name</ui-label>
            <ui-input slot="content"></ui-input>
        </ui-prop>
        
        <ui-prop>
            <ui-label slot="label">Color</ui-label>
            <ui-color slot="content"></ui-color>
        </ui-prop>
        
        <ui-prop>
            <ui-label slot="label">Select</ui-label>
            <ui-select slot="content">
                <option value="1">Lorem ipsum dolor sit amet consectetur, adipisicing elit. Sit, sint.</option>
                <option value="2">Sapiente ratione esse voluptatibus repudiandae illo numquam quas nulla id.</option>
            </ui-select>
        </ui-prop>

    </div>
</div>

然后我们通过 面板 -> extension-vue -> 默认面板 来查看面板效果：

这样看起来不太美观，标题可以居中显示，而且 ui-prop 之间得加点间距。

3.x 版本的 UI 组件没有 2.x 的 ui-box-container 组件来框柱 ui-prop，看起来也不太好看，来看看 2.x 的效果：

既然 3.x 没有，那我们就用 CSS 来实现一个，在 index.css 中添加以下样式：

/* index.css */
h1 {
    /* 文本居中 */
    text-align: center;
}
.box {
    /* 外边距 10px */
    margin: 10px;
    /* 内边距 5px */
    padding: 5px;
    /* 虚线边框 */
    border-style: dashed;
    /* 边框宽度 1px */
    border-width: 1px;
    /* 边框颜色为灰色 */
    border-color: gray;
}
ui-prop {
    /* 添加上边距 5px */
    margin-top: 5px;
}

然后我们将所有 ui-prop 组件添加到一对 <div></div> 标签中，并为 div 添加 css 中定义的 box 样式。

<!-- index.html -->
<div>
    <div id="app">

        <!-- 所有 UI 组件写在 <div id="app"></div> 标签内 -->

        <h1>Extension Vue</h1>

        <div class="box">
            <ui-prop>
                <ui-label slot="label">Checkbox</ui-label>
                <ui-checkbox slot="content"></ui-checkbox>
            </ui-prop>
            
            <ui-prop>
                <ui-label slot="label">Name</ui-label>
                <ui-input slot="content"></ui-input>
            </ui-prop>
            
            <ui-prop>
                <ui-label slot="label">Color</ui-label>
                <ui-color slot="content"></ui-color>
            </ui-prop>
            
            <ui-prop>
                <ui-label slot="label">Select</ui-label>
                <ui-select slot="content">
                    <option value="1">Lorem ipsum dolor sit amet consectetur, adipisicing elit. Sit, sint.</option>
                    <option value="2">Sapiente ratione esse voluptatibus repudiandae illo numquam quas nulla id.</option>
                </ui-select>
            </ui-prop>
        </div>

    </div>
</div>

这样，我们的面板就变得整洁了起来：

注意：编写好 html 后，需要关闭面板重新打开才能看到修改后的内容。

使用 ui-prop 时需要注意 slot 的用法，slot="label" 的组件会放到 ui-prop 左边的显示区域，slot="content" 则是显示在右边的显示区域，如果在 ui-prop 标签对中添加元素而不使用 slot 属性的话，就会被另起一行显示。

如果我们想在 Checkbox 的 ui-prop 中再添加一个 ui-checkbox 元素，且不添加 slot 属性的话，就会变成如下的效果：

<!-- index.html -->
...
<ui-prop>
    <ui-label slot="label">Checkbox</ui-label>
    <ui-checkbox slot="content"></ui-checkbox>
    <ui-checkbox></ui-checkbox>
</ui-prop>
...

所以正确的做法应该是：

<!-- index.html -->
...
<ui-prop>
    <ui-label slot="label">Checkbox</ui-label>
    <ui-checkbox slot="content"></ui-checkbox>
    <ui-checkbox slot="content"></ui-checkbox>
</ui-prop>
...

吐槽：UI 组件面板中的示例代码很好，但是详细解释太少了，要么就应该像 2.x 一样在官方文档中详细写出每个属性的用法。

至此，我们已经尝试使用 UI 组件、HTML 原生标签、CSS 样式来完成基本的面板布局，接下来就可以靠搭积木的方式打造自己的扩展面板了。

如果对 HTML 和 CSS 不熟悉，或者已经忘得差不多了，可以到 W3school 官网找你想要的内容。

使用 Vue3 的特性

我们来做一个根据扩展名来统计文件数量的扩展。

编写逻辑代码

先打开 extension-vue/src/panels/default/index.ts，这是面板的入口文件。

在模板代码中，我们主要修改 ready 函数中的内容，ready 函数是面板启动后触发的钩子函数。

在 ready 函数体中，有如下的代码：

import { createApp } from 'vue';
// ...
module.exports = Editor.Panel.define({
    $: {
        app: '#app',
    },
    ready() {
        const app = createApp({});
        app.mount(this.$.app);
    }
})

这段代码的意思就是创建一个 Vue App 挂载到 #app 标签上，就是为什么我们在 index.html 中需要把布局写到 <div id="app"></div> 标签对中的原因。

在这篇演示中，我们的逻辑代码主要写在 createApp({}) 中。

首先我们定义两个数据，用于存放每个扩展名对应的文件数量和文件的总数量：

createApp({
    data() {
        return {
            /** 扩展名对应的文件数量 */
            fileCount: {},
            /** 文件总数量 */
            fileNum: 0
        }
    }
})

接着我们来写主要的逻辑，将写在 methods: {} 中，data 中定义的数据我们可以通过 this.xxx 取到。

import { readdirSync, readFileSync, statSync } from 'fs-extra';
import { extname, join } from 'path';
// ...
createApp({
    data() {
        return {
            /** 扩展名对应的文件数量 */
            fileCount: {},
            /** 文件总数量 */
            fileNum: 0
        }
    },
    methods: {
        checkAssets() {
            // 定义两个数据的临时变量
            let fileCount: {[key: string]: number} = {};
            let fileNum = 0;
            // 获取 assets 文件夹的路径
            let assetsPath = join(Editor.Project.path, "assets");
            let checkDir = (dirPath: string) => {
                // 获取文件夹下所有的文件名
                let files = readdirSync(dirPath);
                // 遍历文件名
                files.forEach((fileName) => {
                    // 当前文件的路径
                    let subPath = join(dirPath, fileName);
                    // 文件的信息
                    let stat = statSync(subPath);

                    if (stat.isDirectory()) {
                        // 如果文件是个目录，递归查找
                        checkDir(subPath);
                    }
                    else if (stat.isFile()) {
                        // 获取文件的扩展名
                        let extName = extname(fileName);
                        if (extName != "" && !fileCount[extName]) {
                            fileCount[extName] = 1;
                        }
                        else if (extName != "" && fileCount[extName]) {
                            fileCount[extName] += 1;
                        }
                        else {
                            if (fileCount["other"]) {
                                fileCount["other"] += 1;
                            }
                            else {
                                fileCount["other"] = 1;
                            }
                        }
                        fileNum++;
                    }
                })
            }

            checkDir(assetsPath);
            // 将临时变量赋值给 data 中定义的变量
            this.fileCount = fileCount;
            this.fileNum = fileNum;
        }
    }
})

代码中我们用到了 Editor.Project.path 接口，用来获取项目目录路径，可以查看 Editor API 说明文档来查询需要的功能。

我们这段逻辑需要在面板打开时就执行，所以我们需要用到生命周期钩子中的 beforeMount 生命周期：

// ...
createApp({
    data() {
        return {
            /** 扩展名对应的文件数量 */
            fileCount: {},
            /** 文件总数量 */
            fileNum: 0
        }
    },
    methods: {
        checkAssets() {
            // ...
        }
    },
    // 挂载应用之前
    beforeMount() {
        this.checkAssets();
    }
})

这样，我们的逻辑代码就写好了。

重要：TS 代码需要通过 tsc 命令编译成 JS 代码才能在扩展中生效，可以在终端中执行命令 npm run build，来编译 TS 脚本，或者执行 npm run watch 来监听 TS 脚本的变化，自动编译。

使用 Vue3 来布局

我们要对 index.html 进行重新布局，先删除掉之前的 UI 组件示例代码，我们重新编写一套：

<!-- index.html -->
<div>
    <div id="app">

        <h1>Extension Vue</h1>

        <div class="box">

            <ui-prop v-for="(value, key) in fileCount">
                <ui-label slot="label">{{ key }}</ui-label>
                <ui-input 
                    slot="content" 
                    readonly
                    :value="value"
                >
                    <span slot="suffix">个文件</span>
                </ui-input>
            </ui-prop>

            <ui-prop>
                <ui-label slot="label">总计</ui-label>
                <ui-input 
                    slot="content" 
                    readonly
                    :value="fileNum"
                >
                    <span slot="suffix">个文件</span>
                </ui-input>
            </ui-prop>

        </div>

    </div>
</div>

这里我们用到了列表渲染中的 v-for 来显示出所有扩展名对应的文件数量。

:value 是 v-bind:value 的简写，详情可参考 Attribute 绑定，通过这个方法，我们将 data 中定义的两个值绑定到 ui-input 标签的 value 属性上。

这样，我们基本算是完成了这个插件的主要功能，让我们通过 面板 -> extension-vue -> 默认面板 打开面板看看效果吧：

看来 Cocos Creator 3.7.3 的 Hello World 模板项目的 Assets 文件夹下有 58 个文件。

来点交互

我们这个扩展有个问题，他只能在打开面板的时候统计文件数量，如果我们在不关闭面板的情况下增删 Assets 目录中的文件，面板上的数据就不会刷新，我们为面板加一个按钮来手动刷新数据。

<!-- index.html -->
<div>
    <div id="app">

        <h1>Extension Vue</h1>

        <div class="box">
            <!-- ... -->
        </div>

        <div style="text-align: center;">
            <ui-button type="primary" @confirm="checkAssets">
                <ui-icon value="refresh"></ui-icon>
                刷新
            </ui-button>
        </div>

    </div>
</div>

这里我们用到了事件处理，使用 @confirm 绑定了 checkAssets 函数，UI 组件支持的事件我们可以在 UI 组件面板 中查看：

其中 Events 就是该组件支持的事件名，示例代码也给出了 Vue 的写法。

吐槽：Vue 示例代码中应该是用 methods: {}，不要将 Vue 示例代码原封不动的 Copy 到脚本里，会变得不幸。

在这段代码中，我们将 ui-button 也装进了一个 div 中，我们可以直接在标签中添加 style 属性更改标签的样式，但如果 style 内容较多，建议还是写在 index.css 中。

我们关闭面板，重新打开看看效果：

仍然是 58 个文件。（废话）

不要关闭面板，我们在编辑器的资源管理器中添加一个名为 script 的文件夹，并创建一个 TypeScript 脚本文件，叫 HelloWorld

这时，我们点击 extension-vue 面板中的刷新按钮。

我们发现多了一个 .ts 类型文件，但是总计比之前多了 3 个，另外两个文件分别是 script.meta 和 HelloWorld.ts.meta 文件，这是编辑器自动生成的文件。

至此，你已经尝试了 HTML、CSS、UI 组件、Vue3 列表渲染、Vue3 事件处理、Vue3 生命周期、Editor 接口调用 等内容，相信你对 Cocos 扩展已经有了初步的了解。如果仍有疑问，请积极回帖探讨，我是个插件开发的萌新，本篇文章只是个人的经验总结，如果能让你入门插件开发，那是我的荣幸。

插件开发时，请灵活运用相关的文档：

吐槽：官方文档里是有多语言系统（i18n）文档的，但是这篇文档的入口被隐藏在了基础功能页面中，侧边栏找不到这个 i18n 文档的入口，而且 基础功能 文档，在侧边栏是叫 扩展功能详解，真的迷惑……

彩蛋

在扩展根目录中放入一个 PNG 格式的图片资源，命名为 logo.png，就能在扩展管理器中显示 LOGO 啦。

总结

插件开发的意义在于实现自动化，可以解放部分重复的工作，降低重复工作导致的人工犯错几率，作为程序员，就应该使用程序来帮助自己提高效率（~~这样才能更好的摸鱼~~）。

官方在插件开发的文档方面，从 2.x 开始一直都不太完善，感觉都是徒有文档，入门还是得自己摸索，希望有朝一日能有更完善的插件开发文档。

本篇内容中编写好的插件已经开源到 GitHub 仓库，需要的话请移步仓库查看。

另外，如果本篇文章并不能让你入门插件开发，论坛中也有其他大佬写的开发指南，可以参考他们的帖子：

[muzzik 教程]：3.x 插件开发指南

【muzzik教程】：插件开发之道

手把手教你如何使用 rollup + vue单文件工作流开发 3.x 插件

【插件开发】升级Vue2.x+Element-ui+组件式开发Creator2.x

CosmoLau 的个人博客

扩展插件的开发与维护

Cocos Creator 扩展插件的开发与维护

项目准备

版本管理

独立仓库

Cocos 项目仓库

自动化流水线

版本检测

踩坑经验

依赖包版本

node 版本

Element-plus 的根 DOM

外部链接

连续构建

示例扩展插件简介

结语

2025 年终总结

2025 年终总结

站点建设

生活与工作

年度新物

笔记✍🏻

Git 客户端

数码产品

AI

技术栈

结语

在安卓平板上编写代码

在安卓平板上编写代码

前言

准备工作

vscode.dev——代餐

Termux——Android Subsystem for Linux

code-server——启动

编码环境

其他说明

后记

Windows 11 安装相关备忘录

情景

备忘

事前准备

安装引导

修改用户名

无密码登录

本地 Git 仓库

驱动相关

BIOS 相关

站点记录

2024.10.31

2024.5.20

2024.4.16

2024.4.1

2022.10.18

使用 Docker 快速搭建《我的世界》（Minecraft）服务器

快速部署

修改服务器参数

常用参数

Docker 常用命令

踩坑分享

参考

使用 VitePress 移植 Cocos 文档

自动化移植

VitePress 移植踩坑

img 标签路径错误

丢失终止标签

错误的扩展名

结尾

相关链接

【从零开始的插件开发】使用 CC3.x + UI组件 + Vue3 开发一个插件

前言

为何选择 Vue3 模板开发？

创建扩展

使用 UI 组件布局

使用 ui-prop 组件

使用 Vue3 的特性

编写逻辑代码

使用 Vue3 来布局

来点交互

彩蛋