不过目前阶段 OXLint 还是无法完整替代 ESLint ，只能是以 OXLint 为主， ESLint 为辅，但是两者可以完美结合，对项目来说，仍然可以以一套 Lint 方案去解决代码问题， OXFmt 倒是可以完美代替 Prettier 原生规则，只是部分插件仍然需要取舍，例如 Markdown 的盘古之白格式化，我只能暂时舍弃。

由于需要两套 Lint 同时工作，所以这个配置包还没有正式定名为 oxc-config ，暂时只称之为 Integration ，一个集成方案或者说是一套工作流。

这是我在 GitHub 上发布的一个开源项目。如果它对你有帮助，欢迎前往 bassist 点一个 Star。

@bassist/oxc-integration 是一个 Oxc 优先的工作流包，适合希望现在就用上带类型提示的 oxlint.config.ts 与 oxfmt.config.ts，同时在 Oxc 能力尚未完全覆盖时保留 ESLint 兜底能力的项目。

使用方法

通常只需要四步：

1. 安装依赖（参考：安装）
2. 添加 oxlint.config.ts（参考：Oxlint 快速开始）
3. 添加 oxfmt.config.ts（参考：Oxfmt 快速开始）
4. 只有在项目需要 fallback coverage 时，再补 eslint.config.js（参考：ESLint Fallback 快速开始）

安装

npm i -D oxlint oxfmt @bassist/oxc-integration

如果你的项目需要 ESLint fallback，请再安装对应框架所需的 ESLint 生态依赖。

编辑器设置

oxlint / eslint 的 CLI 检查结果，与编辑器里的实时诊断并不是同一件事。

如果你希望在编码过程中就获得 Oxc 的实时 lint 提示，还需要额外安装对应的编辑器插件。否则就可能出现“执行 lint 命令时能查出错误，但编辑器里没有任何 提示”的情况。

• VS Code / Cursor：安装官方 oxc.oxc-vscode 扩展
• 其他编辑器：参考 Oxc 官方的编辑器接入文档

官方文档： https://oxc.rs/docs/guide/usage/linter/editors.html

Oxc 的编辑器扩展会通过项目本地的 oxlint --lsp 工作，因此也请确保项目的 devDependencies 里已经安装了 oxlint。

如果你使用 VS Code 或 Cursor，也可以在项目里补一个 .vscode/settings.json，让保存时修复和类型感知检查更完整：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "always",
    "source.fixAll.oxc": "always"
  },
  "oxc.typeAware": true
}

• source.fixAll.oxc 用于通过 oxc.oxc-vscode 扩展启用 Oxc 的保存时自动修复
• oxc.typeAware: true 可以在 TypeScript 项目里提供类型感知诊断
• 如果你的项目还保留 eslint.config.js 作为 fallback layer，建议继续保留 source.fixAll.eslint
• 如果项目已经是纯 Oxlint 工作流，可以移除 ESLint 的保存时动作

定位

• 如果你需要当前稳定、完整的 ESLint 优先方案，请使用 @bassist/eslint-config
• 如果你想采用 Oxc 优先的工作流，请使用 @bassist/oxc-integration
• 可以把它理解为未来 @bassist/oxc-config 的过渡形态

工作方式

@bassist/oxc-integration 采用 Oxc-first workflow：

• oxlint 是主 Linter
• eslint 是兜底 Linter，用来补齐 Oxc 还没完全覆盖的规则
• oxfmt 是主 Formatter

这也是为什么某些项目现在仍然会同时保留 oxlint.config.ts 和 eslint.config.js。 它们不再是两个并列的主配置文件，而是：

• oxlint.config.ts：主 Lint 配置
• eslint.config.js：兜底 Lint 配置

在这些 fallback presets 内部，会自动接入 eslint-plugin-oxlint，用于关闭那些已经由 Oxlint 覆盖的 ESLint 重叠规则。

什么时候需要 ESLint Fallback

如果 Oxc 已经足够覆盖你的项目，可以只使用 oxlint.config.ts。 如果项目仍然依赖框架或生态特定的 ESLint 能力，则再补一个 eslint.config.js。

通常可以这样理解：

• base / node：很多场景只用 Oxlint 就够了
• react：大多数情况下可以 Oxc 优先，但很多项目仍建议保留 ESLint fallback
• vue：默认建议保留 ESLint fallback
• next：默认建议保留 ESLint fallback
• tailwindcss：优先使用 oxlintPresets.tailwindcss() 通过 Oxc JS plugin lint；如果项目仍需要 ESLint 专属覆盖，再补 ESLint fallback
• vitest：如果你需要更完整的测试规则，建议保留 ESLint fallback

内建的 Fallback Coverage

当前 @bassist/oxc-integration 已内建这些 ESLint fallback presets：

• javascript
• typescript
• jsx
• imports
• jsonc
• markdown
• react
• tailwindcss
• vue
• next
• vitest

当前暂不纳入这个 Oxc-first 工作流范围的内容：

• lint-md
• 基于 Prettier 的 Markdown 内容工作流

这些能力后续可以单独作为内容层工作流再设计。

配置总览

Oxlint 快速开始

Base TS/JS

// oxlint.config.ts
import { defineOxlintConfig, oxlintPresets } from '@bassist/oxc-integration'

export default defineOxlintConfig(oxlintPresets.base())

React

// oxlint.config.ts
import { defineOxlintConfig, oxlintPresets } from '@bassist/oxc-integration'

export default defineOxlintConfig(oxlintPresets.react(), oxlintPresets.vitest())

Vue

// oxlint.config.ts
import { defineOxlintConfig, oxlintPresets } from '@bassist/oxc-integration'

export default defineOxlintConfig(oxlintPresets.vue(), oxlintPresets.vitest())

如果你需要官方 oxlint 类型，请直接从 oxlint 包导入，而不是从本包导入。

Oxlint 内建默认值

oxlintPresets.base() 并不是空壳，它已经内置了这个包约定的 Oxc 基线配置。

当前内建默认值包括：

• plugins：typescript、oxc
• categories：
  • correctness: error
  • suspicious: error
  • pedantic: warn
  • style: off
• 基础规则覆盖：
  • typescript/no-explicit-any: off

然后更高层的 presets 会在这份基线上继续扩展：

• oxlintPresets.node() 会补充 Node 运行时环境
• oxlintPresets.react() 会补充 react、react-perf、jsx-a11y
• oxlintPresets.tailwindcss() 会通过 Oxlint JS plugins 加载 eslint-plugin-better-tailwindcss
• oxlintPresets.vue() 会补充 vue
• oxlintPresets.vitest() 会补充 vitest

如何扩展 Oxlint Presets

建议先使用内建默认值，再把项目特有的差异作为额外配置传入。

// oxlint.config.ts
import { defineOxlintConfig, oxlintPresets } from '@bassist/oxc-integration'

export default defineOxlintConfig(oxlintPresets.react(), {
  rules: {
    'no-console': 'warn',
  },
  ignorePatterns: ['fixtures/**'],
})

可以把 presets 理解成默认基线，把额外传入的对象理解成项目级扩展层。

Tailwind CSS

// oxlint.config.ts
import { defineOxlintConfig, oxlintPresets } from '@bassist/oxc-integration'

export default defineOxlintConfig(
  oxlintPresets.react(),
  oxlintPresets.tailwindcss({
    entryPoint: './src/styles.css',
  }),
)

Tailwind preset 会通过 Oxlint JS plugins 使用 eslint-plugin-better-tailwindcss，让 Tailwind CSS v3 和 v4 项目共用同一套 class linting 规则。

ESLint Fallback 快速开始

Vue / Next / 复杂 React 项目

// eslint.config.js
import { defineEslintConfig, eslintPresets } from '@bassist/oxc-integration'

export default defineEslintConfig(
  eslintPresets.imports(),
  eslintPresets.react(),
  eslintPresets.tailwindcss(),
  eslintPresets.vitest(),
)

如果是 Vue 项目，把 react() 换成 vue() 即可。 如果是 Next 项目，请使用 next()。 只有项目真的在使用 Tailwind CSS 时，才需要再加上 tailwindcss()。

Markdown 内容 lint

// eslint.config.js
import { defineEslintConfig, eslintPresets } from '@bassist/oxc-integration'

export default defineEslintConfig(eslintPresets.markdown())

如果你只想为 Markdown 文件开启独立的 lint 行为，而不希望把它并入 lint-md 或基于 Prettier 的内容工作流，可以使用 markdown()。

Oxfmt 快速开始

建议优先使用带类型提示的 oxfmt.config.ts，这样配置结构会与官方 formatter API 保持一致。

// oxfmt.config.ts
import { defineConfig } from 'oxfmt'
import { oxfmtConfig } from '@bassist/oxc-integration'

export default defineConfig(oxfmtConfig)

如果你想覆盖默认值：

// oxfmt.config.ts
import { defineConfig } from 'oxfmt'
import { getOxfmtConfig } from '@bassist/oxc-integration'

export default defineConfig(
  getOxfmtConfig({
    semi: true,
  }),
)

oxfmt . 会自动发现 oxfmt.config.ts，所以通常不需要额外显式传入配置路径。

如果你需要官方 formatter 类型，请直接从 oxfmt 包导入，而不是从本包导入。

推荐脚本

{
  "scripts": {
    "lint": "oxlint .",
    "lint:eslint": "eslint .",
    "lint:full": "npm run lint && npm run lint:eslint",
    "format": "oxfmt ."
  }
}

推荐用法：

• base / node 项目先从 lint 开始
• vue、next、以及较复杂的 react 项目默认建议使用 lint:full

虽然是个 Breaking Change ，但对用户来说迁移成本不大，并且有了一些更灵活的用法（例如组合式函数），我自己则在重写源码时积累了一些思考点，在这篇文章里分享一下。

本文说明 vue-picture-cropper 从 v0.x 升级到 v1.x 时，在打包方式、样式加载和实例管理上的设计取舍与原因。

为什么会有这个包

在谈 1.x 的设计之前，有必要先回顾一下 0.x 的初衷。

0.x 的第一个版本发布于 2020 年 11 月。当时 Vue 3.x 刚刚发布，整体生态尚处于早期阶段，许多常用库还未完成适配，工程实践也尚未完全稳定。这导致当时的 Vue 3 业务项目很容易因为生态不足而延误工期。

因此，这个包最初并不是面向通用场景的组件库，而是一个为业务项目快速适配的个人小工具。那个时候我的设计目标非常明确：

• 快速为 Vue 3 提供一层可用的 Cropper 封装
• 尽可能降低接入成本
• 以 “开箱即用” 为优先原则

因此在 0.x 中选择将 cropperjs 内置打包，用户只需安装一个包即可使用。

这个处理方式从当时的设计目标来看，是合理的取舍 —— 它优先解决了 “可用性” 和 “便捷性” 的问题，而不是工程边界与依赖模型的完备性。

但这几年随着项目逐步被更多场景使用，工程规模扩大、依赖关系复杂化，这种早期的便捷型设计也逐渐暴露出局限性。

1.x 的调整，并不是对 0.x 的否定，而是在使用场景变化之后的一次架构升级。

为什么仍然是 Cropper.js 1.x

虽然 Cropper.js 主分支已经切换到 2.x，但 v1 与 v2 在架构和使用方式上存在显著差异：

基于以上差异，选择 v1 的工程考量如下：

• 稳定可预测的 API，方便组件封装与调用
• 低迁移成本与低学习成本，保持本库用户现有使用习惯
• 生态友好，遇到问题更容易查找和解决
• 面向现状工程使用，确保构建、SSR 和多实例场景可控

因此，本库依然选择依赖 Cropper.js 1.x ，而非 2.x ，以保证成熟稳定、可维护和生态兼容性。

如果希望使用 Cropper.js 2.x 的现代 Web Components 架构，建议直接使用 Cropper.js 原生库，而非本库的 Vue 封装层。

为什么仅提供 ESM 版本

从 1.x 开始，本库仅以 ESM（ES Modules）形式发布，不再提供 CommonJS (CJS) 或 IIFE 构建版本。

背景与原因：

• 现代 Vue 项目默认使用 ESM

  绝大多数 Vue 3 项目都基于 Vite 或其他现代打包工具，这些环境原生支持 ESM。提供 CJS 或 IIFE 构建在这些场景下意义不大，同时增加维护成本。

• IIFE / CDN 使用量极低

  通过 CDN 分发 IIFE 构建的场景在实践中非常少见，本库统计和社区反馈均显示几乎无人使用。继续提供会增加打包体积和测试负担，但对用户价值有限。

• 简化构建与维护

  移除 CJS/IIFE 后，库的构建流程更简单，TypeScript 类型和模块导出更一致，也避免了 CJS 下 default + named export 的潜在混乱问题。

如果你的项目依赖 CJS / IIFE，请迁移到支持 ESM 的环境，例如使用 Vite、Nuxt 或现代 Webpack 版本。

关于 Bundle 的调整

在 0.x 中，Cropper.js 作为内部依赖被打包进 vue-picture-cropper 的产物中，用户只需安装一个包即可使用：

# 0.x 时的安装方式
npm i vue-picture-cropper

而在 1.x ，Cropper.js 不再被打包进本库的 Bundle ，需要由使用方在项目中显式安装并锁定 Cropper.js 1.x：

# 1.x 需要这么安装
npm i vue-picture-cropper cropperjs@^1

虽然 0.x 看起来方便，但在工程项目里存在这样的问题：

cropperjs 被打包进 vue-picture-cropper ，如果用户项目中也单独使用了 cropperjs ，或其他库也依赖 cropperjs ，就可能出现：多份 cropperjs 、多个实例冲突、工程产物体积变大

简单来说，0.x 是 “内置运行时依赖的封装组件” ，而 1.x 是 “对等依赖（peer dependency）模式下的 Vue 适配层” 。

这样做带来的好处，体现在在运行时层面是：

• 避免重复打包与多实例问题（由宿主项目统一管理版本，只会存在一份依赖）
• 保证运行时构造函数来源唯一
• 降低原型链与 instanceof 判断异常的风险

体现在工程层面是：

• 将版本控制权交还给项目本身
• 避免 “幽灵依赖” 式的隐式依赖关系
• 消除因传递依赖升级带来的不可预测风险
• 更符合现代包管理最佳实践（更小的 Bundle 、更好的 Tree-Shaking ）
• 让库职责更加单一清晰

注：“幽灵依赖（phantom dependency）”指代码运行时依赖某个包，但该包未在当前项目的 package.json 中显式声明。这种情况通常源于 Node.js 的模块解析机制能够访问 node_modules 中的任意已安装包，从而导致依赖关系在项目层面不可见。

关于样式加载方式的变更

和 v0.x 不同，从 1.x 开始不再自动注入样式。

在 v0.x 中，样式会被打包为字符串，并在组件加载时动态创建 <style> 标签插入到页面中，例如：

// v0.x 时的源代码设计
import { loadRes } from '@bassist/utils'
import cropperStyle from 'cropperjs/dist/cropper.css?inline'
import vpcStyle from './style.css?inline'

loadRes({
  type: 'style',
  id: 'cropperjs',
  resource: cropperStyle,
})

loadRes({
  type: 'style',
  id: 'vue-picture-cropper',
  resource: vpcStyle,
})

从 1.x 开始，需要主动在项目的入口文件导入组件样式：

// 此处是业务项目，需要主动导入 Cropper.js 样式和 VuePictureCropper 样式
import 'cropperjs/dist/cropper.css'
import 'vue-picture-cropper/style.css'

为什么移除自动注入？

自动注入样式在早期虽然方便，但也带来一些问题：

• 可控性低：样式在组件加载时才插入，难以统一管理和覆盖全局主题
• Tree-Shaking 无效：打包时无法有效剔除未使用的样式
• 冲突与重复：在大型工程或多实例场景下，可能会重复注入或覆盖其他样式
• 一致性问题：SSR、CSS Modules 或其他构建工具环境中，动态注入样式可能导致渲染不一致

改为显式导入后：

• 项目可以统一管理样式入口
• 支持 Tree-Shaking 和按需加载
• 与现代前端构建工具和工程实践高度兼容

在 1.x ，样式加载更透明、可控、可维护，符合现代前端工程化最佳实践。

关于实例的获取方式调整

在 v0.x 版本中，cropper 实例是通过模块级变量管理的：

// 0.x 源码设计
export let cropper: CropperInstance | null

// 使用 0.x 业务
import VuePictureCropper, { cropper } from 'vue-picture-cropper'

这种设计带来了一些限制：

• 多实例冲突：同一页面同时使用多个裁剪框时，必须额外包一层子组件，否则实例会互相覆盖。
• 逻辑复用不直观：开发者在多实例场景下调用方法或复用逻辑时不够方便，使用体验受限。

因此 1.x 完全重构了实例管理方式：

• 组件实例独立管理 Cropper

  每个 VuePictureCropper 组件拥有自己的状态，不再依赖模块级变量，保证实例相互独立。

• 通过组件 ref 直接获取实例

  开发者可以安全地调用 getDataURL、getBlob、getFile 等方法，无需担心覆盖或冲突。

• 支持多实例和逻辑复用更简单

  在同一页面中同时存在多个裁剪框，各实例互不干扰，操作逻辑更清晰、可复用性更高。

如果希望在纯逻辑中使用裁剪能力，而不依赖模板 ref，可以使用 1.x 提供的组合式函数 useCropper，直接获得与实例绑定的控制器，实现逻辑层面的复用和集中管理。

写在最后

总的来说，1.x 在 Bundle、样式和实例三方面做了统一取舍：依赖与样式由使用方显式管理，实例与组件一一对应。这样既便于构建与 SSR，又支持多实例与逻辑复用。

虽然是一个 Breaking Change ，但 1.x 的 VuePictureCropper 组件 Props 仍然保持和 0.x 一致，主要有以下不同点：

1. 依赖与版本变化
2. 组件内置样式的载入方式变化
3. 获取 Cropper 实例的方式变化

具体迁移步骤请参考 从 v0.x 迁移 以及 在线示例 。

开源社区与 AI 编程

梳理了这一年的变化，还是先从开源说起吧，今年在 GitHub 上的活跃度，勉强保持了打卡式活跃……

搞错了，这是黄村地铁站的 Commit ……

哈哈哈哈哈拍摄于 2025-12-30 晚上下班后，估计有人看到我在那拍，毕竟那是个人来人往的换乘站，还是在人最多的拐弯处，大家都在赶路，就我突然站在那对着墙拍照！

我的活跃在这里，截图还是生成自 GitHub Contributions ，用了好几年了这个工具。

活跃度断崖式下降，有效的新开源工具 0 ，新项目 0 。

因为 AI 辅助编程的发力，从三月份开通 Cursor Pro 开始，加上后面交叉使用的 GPT 、 Claude 、Gemini …… ，几乎全年都在 Vibe Coding ，日常已经转为一名 Prompt 工程师……

AI 发力带来的好处就是提高了生产力，解放了劳动力；带来的副作用就是好像一瞬间失去了想做点什么的动力，好像什么都能用 AI 搞，好像什么都没必要分享了，都是问一下 AI 就行。

所以今年一直只是在私有仓库里尝试一些乱七八糟的东西，或者写点私有笔记，真正拿来搞点什么东西分享到开元社区的，没有，下次一定！

这一年的工作

在去年 2024 的年终总结 里提到公司的主力项目今年要 Release ，做到了，包括相关的硬件产品也推出了几个比较基础的型号，市场反馈和用户反馈还可以，这一年的付出还是得到了肯定。

年底公司也组织了一次团建，那天上午还开了个总结会，然后分组讨论讨论讨论着被我们产品妹子推上去讲了两句，留了张年度照片（就是旁边玩手机这个人……），哈哈哈哈我就不露脸了，露个文身看得出是我就行。

前面说到在开源一点都没产出，不过在公司里产出还算可以吧，AI 解放了双手，有更多的时间去思考和沉淀，留下了几十篇技术文档，完成的需求功能也不算少，几乎每个版本都有自己实现的东西，做的东西有人用，不论是开源还是公司产品，这一点都是成就感满满的！

总的来说工作方面我对自己也是挺满意的，有一些成果算是超出我自己的预期，虽然也依然有一些属于我自己的能力欠缺以及业务痛点还需要解决。

这一年公司也入职了很多技术超级无敌强的大佬，性格也都很好，很务实很沉稳，能一起共事真是十分荣幸，新的一年公司产品线也还会继续壮大，应该也是继续很忙，下一年的总结应该会更好。

另外，还有了一件很有纪念意义的工作服，设计灵感来自我们的系统界面，笑死，以后写 BUG 小心点，不然穿出去被人追着打...

关于生活

这一年依然选择了宅了一年，哪也没去玩，不过翻阅过去一年的朋友圈，也是有一些有意思的事情发生。

简单摘录一点，也不放太多哈哈哈哈，不然就是流水账了！

加了个文身

六月份终于把三年前就想纹的图案构思了出来，两株麦穗，源自广州的别名 “穗城” 和她的 “五羊衔谷” 传说，从我的贝斯两侧缓缓伸出，绕肩而上，同根生长。

这个图案名为《同根》，其实也是我最喜欢的吉他手黄贯中的一张专辑名称，同根 也是这张专辑的同名主打歌曲，歌曲的创作与饥荒和互助有关，这个文身的出处也是。

另外对于我来说，还有另外一层意义，广州这座城市在我年龄还是个位数的时候，浓厚的历史沉淀就对我有着精神上的吸引，长大后在这里读书再到出社会独立，又从物质上帮我扎下了根，直到现在依然喜欢这座城市。

全部文身可以在 文身专栏 找到，这里记载了每个文身的意义。

重新设计了博客

四月份那会想重新设计博客首页，给博客找了好久 Hero 区域的素材搭配，最终敲定的方案又回到 “最好的素材就在身边” 的原则，用自己的第一个文身。

如今也快过去一年了，还是特别喜欢，越看越喜欢，包括我的手机壁纸也一直是这个文身。

文身专栏

重新设计博客的时候，也顺带设计了我的文身专栏，第一次这么正式向大家介绍我的文身和它们背后的故事，以及合作了十年的纹身师!

再贴下传送门：文身专栏 。

手写的贺卡

一对一轻量级资助了个山区小女生一点点费用，竟然收到教育局寄来的小朋友手写贺卡，看到这个涂改液，小时候自己涂改作业的事情回忆起来真美好！云养女儿的感觉！

还没全秃

虽然这两年明显感觉到发量在变少，但还好还没全秃，而且有时候起床后蓬松感还不错！

要是哪天快秃了，我就去搞个脏辫，脏辫玩够了就剃光头去！

发发发

原来真有人随机到 888 的咖啡订单号码，是谁？是我！

让摇滚的声音响彻整个夜晚

去年的总结《本色十年》回忆了十年来的一些工作与生活变化，包括转岗的坚持等一些心路历程。

如今在 2025 年往前看十年，其实 2015 年也是挺有意义的一年，那一年鼓起勇气入职了网易，度过了对我人生十分重要的五年，后来离职的时候还写了一篇《让摇滚的声音响彻整个夜晚》记录我在网易五年里的工作与生活，都是特别美好的回忆！

接下来是 2026 年了，也开始踏上了我文身十年，以及养猫十年的时间点，回头看过去，人生的每一步不在于是否都能踩对，但如果能留下一些有意思的事情，每次往回看十年前，依然能开心，这辈子也就值了。

新的一年

回到最开始，之所以先说开源和 AI ，就是想说我这一年在工作之外其实是有点缺少目标感，说白了就是迷茫。

尽管也学了不少新东西，在工作上也用得游刃有余，但就是总觉得没什么很垂直方向的沉淀，大部分时间都在创造当前的价值优先，缺少一点可持续发展的安全感。

特别是负责了一个很需要专业知识的项目也有一年多了，虽然目前也运行的还行，有吐槽，但不算多，但始终还是处于赶需求赶需求的状态，大部分问题和实现都懂，但在这个领域还是缺少更多的专业知识学习和实际探索，时间不够用。

上一个 OKR 周期在向老板复盘汇报的时候我也说，我始终不敢说这个项目是我在负责，因为我觉得还没有做到我自己很满意的程度，没脸公开啊哈哈，只能做一个默默维护的神秘客。

前两年的总结没有定下什么目标，今年希望能安排好自己的时间去钻研下，最好也仍然能沉淀一些自己的经验记录。

另外也减少点有的没的时间浪费，新东西层出不穷，倒也没必要到处尝试，今年就是一个浪费时间的例子，笑死。

这里的日记就很纯粹的记录生活，不是什么读书笔记、技术笔记等等，那一类的记录对我来说都属于生活之外的事情，冷冰冰没有个人感情，生活日记记录了我每一段生活的喜怒哀乐，还有各种胡思乱想，闲着无聊的时候翻一翻，能够回顾自己过往的生活和成长，别有一番乐趣。

早期的方案

2019 年重新开始写日记那会，我当时的需求主要是晚上睡觉前用手机记录当天的日记，并且有网页版或者桌面客户端可以平时在电脑上看一看稍微管理一下就足够，但那个时候还没什么特别流行的跨平台笔记方案，而且大部分流行的笔记 App 都是广告很多。

加上当时还没有开始接触 NAS ，也没有选择自建存储的想法，后面选择了一款界面比较清爽、自我感觉用户体量比较小的 App（猜的…… ），由于那家公司本职不是做这个笔记 App 产品，所以对 App 利益相关的运营干涉不是太多，所以 “清爽的体验” 一用就这么用了五年多。

但随着长时间深入使用，这也变成了我不想用它的原因，由于 App 不够被重视，以至于多年未维护更新，产生的 BUG 也没有修复，一度让我自己想抽空做一个客户端自己用（根据它的 BUG 表现推测是比较老版本的 React Native 做的）。

新的迁移方案

不过由于工作太忙， “做一个情怀客户端自己用” 这个事情也就一直放着，可以看到我是 23 年开的 Project ，直到现在都没动哈哈哈。

不过拖延症有拖延症的好处，因为这几年陆陆续续听到 Obsidian 、 Logseq 、 Joplin 、 Notion ，以及国产的为知笔记、思源笔记，以及语雀、飞书文档这一类不太纯笔记但也提供了很优秀的笔记功能的产品，有这么多现成的，干嘛还自己搞呢？

而且在开 Project 的那段时间，也开始玩起了 NAS （详见 我的第一台 NAS 一文），玩熟悉之后，用 NAS 来存储这些相对敏感的数据，应该说是最好的选择了。

迁移之前的考虑

有了数据迁移的想法，先梳理看看自己都需要些啥功能。

明确自己的需求

在现阶段，用 NAS 作为数据存储是已经确定的事情，剩下的不确定因素主要还是客户端方案的选择。

客户端之间的选择

支持私有部署的 “单机笔记” 方面，主流的就是 Obsidian 、 Logseq 、 Joplin 、为知笔记、思源笔记 这几款。

基于社区评价、私有化部署的内存占用（ NAS 比较重视）、客户端颜值等维度对比后，就剩下 Obsidian 和 Logseq 两者， Logseq 是比 Obsidian 要晚一点推出的产品，所以它具备了 OB 的一些优点，同时还具有双向链接、块引用等更现代化的功能。

不过社区普遍认为 Logseq 在处理大量笔记时性能稍弱一些，而它基于大纲的组织方式，对我目前以 “日记” 为主的使用场景来说略显复杂。

未来如果要记录其他类型的内容，我可能会选择 Logseq 来做区分，但目前还是选了更为经典的 Obsidian 。

目前的方案

接下来讲讲我目前确定下来的具体架构和配置。

多端同步架构

经过前面的方案对比之后，我的笔记方案整体架构非常简单。

• NAS 作为数据存储中心，并通过自带的 WebDAV 服务对外同步
• 多端则使用 Obsidian 官方提供的桌面和手机客户端，配好对应的同步功能即可和 NAS 进行数据对接

在同步方案的选择上，基于 NAS ，就毫无悬念选 WebDAV 了：

• ✅ 数据完全私有，不依赖第三方服务
• ✅ 局域网内同步速度极快，也可以配合 DDNS 或内网穿透实现外网访问
• ✅ 理论上无限容量，无需额外的订阅成本（硬盘成本算到 NAS 的购买成本里了）
• ✅ Obsidian 有对应的插件支持 WebDAV

其他方案对比

不过 Obsidian 也有其他的同步方案，这里也顺便记录下查过的方案对比，供参考：

飞牛同步客户端

在这里还要提及一个特别的同步方案，那就是飞牛同步，支持 Windows 和 macOS 平台。

飞牛同步的优势在于：

• ✅ 飞牛官方团队维护，与飞牛 NAS 深度集成
• ✅ 配置相对简单，对非技术用户更友好
• ✅ 针对飞牛 NAS 优化，同步性能可能更好

可以在官网下载 飞牛同步客户端 。

不过目前飞牛同步还只有 PC 版本，还没有移动端版本支持。对于我这种需要在 iPhone 上记录日记的场景，WebDAV 方案配合 Obsidian App 是更合适的选择。

但如果你的主要使用场景是桌面端同步文件（不限于 Obsidian ），或者希望有更简单的配置流程，飞牛同步也是一个值得考虑的选择。

使用体验

先说说目前方案的使用体验吧，如果你觉得这套方式也适合自己，再继续往下看配置部分。

旧数据迁移

我之前用的那个笔记 App 不支持导出数据，所以我是通过 DevTools 查看它的 API 请求过程，写了个爬虫把笔记内容爬了回来。

对方的 API 返回的是 HTML ，因此本地又编写了一个 HTML 转 Markdown 的工具进行格式转换（推荐 Remark 系列工具包）。

笔记中的图片原本也是远程 URL ，我在爬取时一并下载到本地，并按日期文件夹归档，再将笔记里的引用路径改成相对路径指向本地图片，当然这些工作也是用脚本处理的。

具体细节这里就不展开了，前端同学对这种流程应该不陌生，而且爬虫这东西也不太方便公开细说。

使用感受

写这篇博客时，我已经迁移到 Obsidian + 飞牛 NAS 四个月了，总体体验可以说是非常满意：

优点：

• ✅ 速度快：局域网同步几乎是秒传，搜索 2000+ 笔记也很流畅
• ✅ 稳定性好：至今未出现同步失败或数据丢失
• ✅ 界面清爽：Obsidian 的界面简洁干净，用起来非常舒适
• ✅ 插件丰富：几乎所有功能都有对应插件支持自定义
• ✅ 数据安全：可以只在局域网内同步，数据不出网更安全
• ✅ 备份方便：在 NAS 端还可以通过 “文件备份” 功能自动备份到其他存储位置

需要注意的点：

• ⚠️ 初次配置有门槛：NAS 端配置简单，但 Obsidian 的客户端选项较多，需要点时间摸索
• ⚠️ 外网访问速度：若 NAS 没有公网 IP ，使用 FN Connect 免费版的访问速度可能偏慢（可考虑付费版）
• ⚠️ 移动端容量：Obsidian 是本地化编辑器，所有文件都会存储在设备上，需确保手机空间充足
• ⚠️ 预防同步冲突：多设备同时编辑时，仍需留意冲突问题

多端同步配置

接下来讲讲怎么围绕 NAS 这个数据中心实现多端同步，主要以飞牛 NAS 端，以及 Obsidian 桌面客户端，先把流程跑通了，在 Obsidian App 的设置也是一样的。

飞牛 NAS 配置

下面的配置步骤都是以 Web 端的操作为例，在飞牛的 App 操作也是类似，按顺序操作即可，需要注意的是，请使用管理员账号 登录飞牛 NAS ，而不要使用普通账号，很多操作需要管理员才可以设置。

创建笔记存储目录

建议在 “文件管理” 中创建一个专门的文件夹，作为数据的存储根目录，比如 database ，这样其他类似的数据托管都可以存档在该文件夹里。

真正存放数据的地方，可以根据需要再建一层目录，例如我的日记是放在 database 的 diary 下。

重要数据建议存放在一个有数据保护的存储空间下，预算不高的话可以像我一样，用两块 2TB 的硬盘创建一个 RAID 1 。

配置 WebDAV 服务

飞牛 NAS 自带 WebDAV 服务，访问 “系统设置 → 文件共享协议 → WebDAV ” ，启用服务。默认的 HTTP 端口号 5005 / HTTPS 端口号 5006 可以直接使用，也可以自行修改。

再点击 WebDAV 界面上的 “设置可见文件夹范围” ，设置允许通过 WebDAV 访问的目录范围，根据自己的需要去限制范围，记得包含刚才的数据文件夹就行。

在 NAS 的 WebDAV 配置界面上，可以看到自己的访问地址是

• http://{你的 NAS 内网 IP}:{端口号}/
• http://{你的 NAS 域名}:{端口号}/

注意，使用 HTTP 或 HTTPS 时，两者的端口号是不一样的

如果需要使用域名访问 WebDAV ，可以在 “系统设置 → 远程访问” 管理 FN Connect 账号，或者在 DDNS 配置域名，具体在这里不过多介绍，飞牛的界面操作还是很清晰的。

Obsidian 桌面客户端配置

在 Obsidian 中，根据最流行的免费同步方案，使用了 Remotely Save ，另外为了统一处理 Markdown 的内嵌文件路径（图片、视频等）的存放位置，我同时使用了 Custom Attachment Location 插件。

仓库与日记设置

启动 Obsidian 后会引导创建一个笔记仓库，其实就是在电脑里选择一个文件夹存档这些笔记，所选的文件夹对于这个仓库来说也是一个根目录的概念。

如果和我一样是用来写日记的，或者是想类似日记一样在同一个文件夹里存档笔记，并且有自己的固定笔记模板，那么可以在 “日记” 设置一些存档规则，例如我选择了将所有日记都归类到 docs 文件夹，而日记模板则归类在 template 文件夹下（模版需要具体到某一个文件的路径）。

内部链接设置

Obsidian 对 Markdown 的链接和图片引用默认是它自己的语法，为了以后兼容其他客户端，建议这里也改成 “基于当前笔记的相对路径” 。

安装插件

插件好像都是从 GitHub 安装的，所以需要确保所处的网络环境可以顺利打开 GitHub 。

1. 打开 Obsidian 设置 → 第三方插件 → 关闭 “安全模式”
2. 点击「浏览」搜索 Remotely Save （必要）和 Custom Attachment Location（可选）
3. 安装对应的插件并启用

同步插件配置

同步插件是核心插件，使用的是 Remotely Save ，这里有几项需要设置：

其他的就根据实际需要调整，或者保持默认就可以了。

附件插件配置

辅助插件目前只用了一个附件管理的 Custom Attachment Location ，从前面的仓库与日记设置可以看到我还有一个 assets 文件夹，这是因为我每天的日记除了文字，还带有不少图片，有时候还会贴视频，如果没有合理归档这些附件，混在一起就太难维护了。

其他选项可以根据自己需要修改，例如图片自动重命名的一些功能。

Obsidian 移动设备配置

我的常用移动设备是 iPhone ，所以直接在 App Store 搜索 Obsidian 即可找到客户端下载，也可以在官网找到其他端的下载。

安装好 App 后，在 iPhone 或其他设备上重复上述步骤进行配置。

总结

日常写笔记时，我的习惯是只在一端更新，写完后同步回 NAS ，下次在另一台设备启动 Obsidian 时，插件会自动比对版本，从 NAS 拉取最新数据，实现双向同步，这种方式在实际使用中没有出现文件冲突，整体体验非常稳定。

从 2019 年开始在第三方 App 上写日记，到现在用 Obsidian + 飞牛 NAS 搭建私有笔记系统，这 6 年的数据迁移总算告一段落。

这套方案在技术上并不复杂，但在内容管理理念上是一次很大的升级：

• 数据完全自控，还可以在 NAS 上定期备份或迁移
• 所有数据本地均有存档，离线也能完整访问与编辑
• Markdown 格式通用、可扩展，不受笔记客户端约束

经过几个月使用，无论是多端同步、搜索速度还是文件安全，都比以往的云笔记方案更可靠，如果你也希望让笔记系统更可控、更长期可维护，这套组合值得一试。

这里有一个关于 ESLint V9 的扁平化配置的 npm 包，内置了一些个人常用的 ESLint 配置，这也是我在 GitHub 上发布的一个开源项目。如果它对您有帮助，请 给它一个 Star ！

一款现代化的扁平 ESLint 配置，适用于 ESLint v9 和 v10 ，由 @chengpeiquan 精心打造。

⚡ 使用方法

使用此 ESLint 配置仅需三步：

1. 安装依赖（参考：🚀 安装）
2. 添加 ESLint 配置文件（参考：📂 配置文件）
3. 在 VS Code 的 settings.json 启用自动 Lint（参考：🛠 VS Code 配置）

这个快速指南可以作为入门辅助，避免遗漏关键步骤 🚀 。

🚀 安装

使用常用的包管理器安装该包：

npm install -D eslint @bassist/eslint-config

注意： 支持 ESLint 9.x 和 10.x，并且需要 TypeScript 版本 >= 5.0.0。

如果使用的是 pnpm，建议在项目根目录添加 .npmrc 文件，并包含以下配置，以更顺利地处理 peer 依赖：

shamefully-hoist=true
auto-install-peers=true

如果仍在使用 ESLint v8，请参考旧版（已不再维护）包：@bassist/eslint。

📂 配置文件

在项目根目录创建 eslint.config.js 文件：

// eslint.config.js
import { imports, typescript } from '@bassist/eslint-config'

// 导出一个包含多个配置对象的数组
export default [...imports, ...typescript]

然后在 package.json 中添加 "type": "module" ：

{
  "type": "module",
  "scripts": {
    "lint": "eslint src",
    "lint:inspector": "npx @eslint/config-inspector"
  }
}

运行 npm run lint 以检查代码，或运行 npm run lint:inspector 在 http://localhost:7777 查看可视化的 ESLint 配置。

Bun 可以直接加载 eslint.config.ts 。如果你通过 Node.js 运行 ESLint，建议改用 eslint.config.mjs，或者按照 ESLint 文档完成额外的设置。

# pnpm 工作流
pnpm lint

🧩 JSONC 预设

如果希望 ESLint 直接检查 JSON 系列文件，可以使用 jsonc 预设：

// eslint.config.js
import { jsonc } from '@bassist/eslint-config'

export default [...jsonc]

jsonc 的默认行为：

• 支持 .json、.jsonc、.json5
• 默认递归排序对象 key（jsonc/sort-keys）
• 默认忽略 package.json，让包清单 key 排序继续交给格式化流程处理

如果你在 VS Code 里通过 ESLint 扩展做校验，并且手动设置了 eslint.validate，记得把 json 和 jsonc 也加进去。

如果需要，也可以在项目里覆盖默认行为：

import { jsonc } from '@bassist/eslint-config'

export default [
  ...jsonc,
  {
    files: ['**/*.json', '**/*.jsonc', '**/*.json5'],
    rules: {
      'jsonc/sort-keys': 'off',
    },
  },
]

✅ 类型安全的配置

为了增强类型安全性，可以使用 defineFlatConfig:

// @ts-check
import { defineFlatConfig, imports, vue } from '@bassist/eslint-config'

export default defineFlatConfig([
  ...imports,
  ...vue,
  // 添加更多自定义配置
  {
    // 为每个配置提供名称，以便在运行 `npm run lint:inspector` 时，
    // 可以在可视化工具中清晰展示
    name: 'my-custom-rule/vue',
    rules: {
      // 例如：默认情况下，该规则是 `off`
      'vue/component-tags-order': 'error',
    },
    ignores: ['examples'],
  },
])

🛠 VS Code 配置

在 VS Code 工作区的 settings.json 添加以下配置，以启用自动 Lint 修复：

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "always",
    "source.fixAll.prettier": "always"
  },
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.useFlatConfig": true,
  "eslint.format.enable": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "json",
    "jsonc"
  ],
  "prettier.configPath": "./.prettierrc.js"
}

关于 prettier.configPath 请查看 格式化工具 部分。

📘 API 参考

defineFlatConfig

定义 ESLint 配置，可选支持 Prettier 和 Tailwind CSS。

API 类型声明：

/**
 * 定义 ESLint 配置，可选支持 Prettier 集成。
 *
 * @param configs 基础 ESLint 配置数组。
 * @param options - 配置选项。
 * @returns 最终的 ESLint 配置数组。
 */
declare const defineFlatConfig: (
  configs: FlatESLintConfig[],
  options?: DefineFlatConfigOptions,
) => FlatESLintConfig[]

选项类型声明：

interface DefineFlatConfigOptions {
  /**
   * 指定用于加载 `.prettierrc` 配置的工作目录。
   *
   * 配置文件应为 JSON 格式。
   *
   * @default process.cwd()
   */
  cwd?: string

  /**
   * 如果 `prettierEnabled` 设为 `false`，则所有与 Prettier 相关的规则和配置都将被忽略， 即使提供了
   * `prettierRules` 也不会生效。
   *
   * @default true
   */
  prettierEnabled?: boolean

  /**
   * 默认情况下，会从当前工作目录读取 `.prettierrc`，并且 `.prettierrc` 文件必须是 JSON 格式。
   *
   * 如果配置文件不是 JSON 格式，或者使用了不同的文件名，可以将其转换为 JSON 规则后传入。
   *
   * 读取自定义配置后，会与默认的 ESLint 规则合并。
   *
   * @see https://prettier.io/docs/configuration.html
   */
  prettierRules?: PartialPrettierExtendedOptions

  /**
   * Tailwind CSS 规则默认启用。如果它们影响了项目，可以通过该选项禁用。
   *
   * @default true
   */
  tailwindcssEnabled?: boolean

  /**
   * 如果需要覆盖 Tailwind CSS 配置，可以传入相应的选项。
   *
   * 如果想要合并配置，可以导入 `defaultTailwindcssSettings`，手动合并后再传入。
   *
   * 如果传入空对象 `{}`，则会使用默认设置。
   *
   * @see https://github.com/schoero/eslint-plugin-better-tailwindcss
   */
  tailwindcssSettings?: TailwindcssSettings
}

createGetConfigNameFactory

createGetConfigNameFactory 是一个灵活的工具函数，用于生成 ESLint 配置命名工具。它可以快速拼接配置名称，确保命名空间一致，并便于组织和管理复杂的规则集。

API 类型声明：

/**
 * 一个灵活的工具函数，用于生成 ESLint 配置命名工具。 它可以快速拼接配置名称，确保命名空间一致，并便于组织和管理复杂的规则集。
 *
 * @param prefix - 表示配置名称前缀的字符串。
 * @returns 一个函数，该函数会将提供的名称片段与指定的前缀拼接在一起。
 */
declare const createGetConfigNameFactory: (
  prefix: string,
) => (...names: string[]) => string

使用示例：

import {
  createGetConfigNameFactory,
  defineFlatConfig,
} from '@bassist/eslint-config'

const getConfigName = createGetConfigNameFactory('my-prefix')

export default defineFlatConfig([
  {
    name: getConfigName('ignore'), // --> `my-prefix/ignore`
    ignores: ['**/dist/**', '**/.build/**', '**/CHANGELOG.md'],
  },
])

为什么要使用它？

• 一致性：强制执行清晰统一的配置命名模式。
• 灵活性：允许为不同项目或范围自定义前缀。
• 简化管理：便于组织和浏览大型 ESLint 配置。

这个工具在构建可复用的 ESLint 配置或维护复杂项目的规则集时尤其有用。

📦 导出的配置

这些是一些常用的配置，如果有额外需求，欢迎提交 PR！

语言支持

• JavaScript
• TypeScript
• JSX
• JSON / JSONC / JSON5
• Markdown

框架支持

• Next.js
• React
• Vue (v2 and v3)

格式化工具

格式化规则默认启用，不会单独导出。如需自定义配置，请通过 defineFlatConfig API 的 options 传入。

• Prettier :
  • 默认会读取 .prettierrc 和 .prettierignore 的内容，并添加到 ESLint 规则中。
  • 如果预期的配置文件不存在，则会使用 内置的 Prettier 规则作为兜底规则。
  • 非以上配置文件并且不喜欢默认规则时，可以通过 defineFlatConfig 的 options.prettierRules 将完整配置传递进来优先作为 ESLint 规则使用
• Tailwind CSS :
  • 使用 eslint-plugin-better-tailwindcss，让 Tailwind CSS v3 和 v4 项目共用同一套 class linting。
  • Monorepo、自定义 CSS 入口或自定义 class selector，可通过 options.tailwindcssSettings 传递。

其它

• Node.js
• Imports
• Regexp
• Unicorn

📚 迁移指南

• 扁平化配置（Flat Configs）不支持 ESLint 8.x 以下的版本。
• --ext CLI 选项已被移除 (#16991) 。

📝 发布日志

详细更新内容请参考 CHANGELOG 。

简单的迁移工作

由于老的服务器上部署的大多是前端项目（数据是连 Serverless 的 API 操作的，不在这台机器上），并且基本都是用 Docker 部署的，所以迁移工作都比较简单，在源码仓库上修改 Workflow 的目标机器 IP 和 SSH Key ，重新运行一次 CI 打包，就可以把新的镜像推送到新的服务器上了。

其他的像 SSL 证书， Nginx 配置，都是拷贝过去后重启一下 Nginx 就搞定，等服务都起来了，去 DNS 解析那里把域名指向新机器的 IP 就迁移完了，都问题不大。

除了有一个 Nest 服务，因为连了 SQLite ，迁移后出现了一点问题。

部署后运行报错

问题倒不是出在 SQLite 上，用 Docker 连接这种嵌入式数据库，都是通过 Volumes 挂载到宿主机器上的，所以访问的数据库文件路径是宿主机器上的路径，知道了这一点，把 SQLite 数据迁移到新服务器上也很简单，并且在新机器上直接用 SQLite 查询数据，也都没问题。

至于在 Docker 里使用 SQLite 本身，只需要在 Dockerfile 里，在安装 libc6-compat 的时候记得一起安装 sqlite 就可以。

# Dockerfile

# Use the official Node.js image as the base image
FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat sqlite

# Set the working directory inside the container
WORKDIR /app

# ...

但是 Docker 容器运行后，访问接口却挂了，通过 docker logs 查询容器的日志，发现启动后这里有个报错：

[Nest] 1  - 02/15/2025, 1:23:01 PM     LOG [InstanceLoader] ScheduleModule dependencies initialized +1ms
[Nest] 1  - 02/15/2025, 1:23:01 PM   ERROR [TypeOrmModule] Unable to connect to the database. Retrying (1)...
Error: Could not locate the bindings file. Tried:
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/build/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/build/Debug/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/build/Release/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/out/Debug/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/Debug/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/out/Release/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/Release/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/build/default/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/compiled/18.20.6/linux/x64/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/addon-build/release/install-root/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/addon-build/debug/install-root/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/addon-build/default/install-root/better_sqlite3.node
 → /app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/lib/binding/node-v108-linux-x64/better_sqlite3.node
    at bindings (/app/node_modules/.pnpm/bindings@1.5.0/node_modules/bindings/bindings.js:126:9)
    at new Database (/app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/lib/database.js:48:64)
    at BetterSqlite3Driver.Database [as sqlite] (/app/node_modules/.pnpm/better-sqlite3@11.7.0/node_modules/better-sqlite3/lib/database.js:11:10)
    at BetterSqlite3Driver.createDatabaseConnection (/app/node_modules/.pnpm/typeorm@0.3.20_better-sqlite3@11.7.0_sqlite3@5.1.7_ts-node@10.9.2_@types+node@20.17.9_typescript@5.7.2_/node_modules/typeorm/driver/better-sqlite3/BetterSqlite3Driver.js:88:41)
    at async BetterSqlite3Driver.connect (/app/node_modules/.pnpm/typeorm@0.3.20_better-sqlite3@11.7.0_sqlite3@5.1.7_ts-node@10.9.2_@types+node@20.17.9_typescript@5.7.2_/node_modules/typeorm/driver/sqlite-abstract/AbstractSqliteDriver.js:171:35)
    at async DataSource.initialize (/app/node_modules/.pnpm/typeorm@0.3.20_better-sqlite3@11.7.0_sqlite3@5.1.7_ts-node@10.9.2_@types+node@20.17.9_typescript@5.7.2_/node_modules/typeorm/data-source/DataSource.js:136:9)
[Nest] 1  - 02/15/2025, 1:23:04 PM   ERROR [TypeOrmModule] Unable to connect to the database. Retrying (2)...
Error: Could not locate the bindings file. Tried:

错误日志分析

在 Node 服务端程序连接 SQLite 是用了 better-sqlite3 这个库，它是 Node.js 中速度最快、最简单的 SQLite 库，在 Nestjs 里也是支持用 TypeORM 来基于这个库操作 SQLite 。

better-sqlite3 的产物

和普通的依赖包直接引入 dist 产物开箱即用不一样，它还需要编译一次原生绑定文件，默认情况下，它会尝试在安装时自动构建原生模块，对比本地在 node_modules 里的目录文件，和 npmjs 上的发布文件列表，会发现线上的发布版少了 better_sqlite3.node 这个文件，提示的报错信息也是少了这个文件。

构建脚本解析

在 better-sqlite3 的 package.json 里，可以看到 install 脚本就是执行这个安装后编译 Node.js 模块的操作。

{
  "scripts": {
    "install": "prebuild-install || node-gyp rebuild --release",
    "build-release": "node-gyp rebuild --release",
    "build-debug": "node-gyp rebuild --debug",
    "rebuild-release": "npm run lzz && npm run build-release",
    "rebuild-debug": "npm run lzz && npm run build-debug",
    "test": "mocha --exit --slow=75 --timeout=5000",
    "benchmark": "node benchmark",
    "download": "bash ./deps/download.sh",
    "lzz": "lzz -hx hpp -sx cpp -k BETTER_SQLITE3 -d -hl -sl -e ./src/better_sqlite3.lzz"
  }
}

这个 npm install 脚本，是 npm 的 生命周期 之一，当执行 npm install 时触发（其它包管理器如 pnpm install 也会触发）。如果 npm 包的根目录下有一个名为 binding.gyp 的文件，当没有自定义 install 或 preinstall 脚本时， npm 将默认使用 node-gyp rebuild 命令对 binding.gyp 进行编译。

node-gyp 是 Node.js 官方提供的跨平台命令行工具，用于编译 Node.js 的原生插件模块。

可以看到 better-sqlite3 的根目录下，也是存在一个 binding.gyp 文件，所以在 install 依赖的时候，better-sqlite3 会尝试使用 prebuild-install 来下载已编译好的二进制文件，如果没有找到匹配的文件，则会退回使用 node-gyp rebuild --release 来手动编译源代码。

better-sqlite3 这行 install 命令的意思是：

1. prebuild-install：

   • 这个命令会首先检查是否有已经构建好的二进制文件（预编译的二进制文件）。 它是由 prebuild-install 这个工具提供的，用来自动下载已编译好的二进制文件，避免在安装时重新编译原生模块，这个步骤是为了加速安装过程，并且能够在大多数情况下避免编译原生代码，尤其是针对不同平台的预编译文件。
   • prebuild-install 会检查与当前 Node.js 版本和操作系统匹配的预编译包，如果找到了，则直接使用。

2. node-gyp rebuild --release：

   • 如果没有找到匹配的预编译文件（比如第一次安装时或没有适用的二进制文件），则会执行 node-gyp rebuild，这会尝试从源代码编译原生模块。
   • node-gyp 是一个用于编译 Node.js 本地模块的工具，它会根据模块中的 C++ 源代码生成并编译 .node 文件。
   • --release 参数表示以发布模式编译（优化后的版本），而不是调试模式。

但以上虽然是理论上的预期方案和兜底方案，但不知道为什么在 CI 机器上居然都没有执行成功，导致最后缺少了这个编译好的二进制文件。

解决思路

既然确认问题就是因为少了这个编译的 Node.js 模块，那么可以尝试手动 build 一下，主动生成 better_sqlite3.node 文件。

因此在 Dockerfile 里，通过 pnpm i 之类安装项目依赖这一步的后面，添加如下代码：

# Dockerfile

# ...

RUN apk add --update --no-cache python3 build-base gcc && ln -sf /usr/bin/python3 /usr/bin/python
RUN cd node_modules/better-sqlite3 && pnpm build-release

# ...

手动安装编译需要的依赖，并手动执行 better-sqlite3 的构建脚本，主动生成运行程序需要的 better_sqlite3.node 文件，然后就一切恢复正常了！

感慨一下

之前 CI 构建没问题的时候是基于 Ubuntu 22.04.5 ，现在构建失败的时候是基于 Ubuntu 24.04.1 ，只能说 CI 机器的新系统环境少了一些预装的依赖，导致 node-gyp build 没有执行成功。

这次自己的主服务器迁移是从旧机器的 CentOS 7 迁移到新机器的 Debian 12 ，在选择 Debian 之前，还一度先装了 Ubuntu 24 ，然后看到一些建议说作为主服务器还是稳定优先，建议用 Debian ，所以就重新装了系统。

没想到话音刚落就在 CI 机器踩了 Ubuntu 的坑，害，对 Linux 这些系统版本不太熟，还是得多多学习呀。

想了两个月的标题

最初也想过用《独立博客的十年》或者是一些其它类似的就事论事的标题，但总觉得不够好，后来想到这十年时间刚好覆盖了我从一个产品运营到前端开发工程师的转变、从大厂光鲜到创业公司更好玩的从容、从广州去深圳又回到广州的生活见识，尽管工作和生活经历了很多变化，但对我个人的内心深处来说，似乎没有受到过多的影响，始终知道自己喜欢的是什么，不会因为外界的干扰而改变。

所以最后脑海里总是停留在《英雄本色》这部电影里，不论是它的中文名，还是英文名《A Better Tomorrow》，或者是它的主题曲《当年情》，都感觉很符合我想要的那种感觉，所以最终才决定用《本色十年》这个标题。

我所热爱的事情

随着年龄的增长，我越来越觉得所谓的本色，就是一个人内心深处最真实的样子，不会因为外界的干扰而改变，也不会因为时间的流逝而改变。

十年前，也就是 2014 年，我的好友吴庸吴老师在 他的博客 上给我加了一个友情链接，他给我配的文案是：

诗人、贝斯手、出色的厨子、编辑、切得一手好图的前端、曾经放荡过的旅行家

十年后，2024 年，这个文案还在他博客上挂着，挂了整整十年。

再看看我在 2023 年刚入职现在这家公司的时候（飞牛 fnOS），在公司同学录里的自我介绍：

纹了一条花臂，钟爱 Blackwork Tattoo 风格，第一个文身是我的琴；

养了三只猫，从 2016 年到现在，超粘人，喜欢抱着我的花臂睡觉；

自己跟自己玩的贝斯手，常用五弦的 MusicMan Neck-Through Bass；

从 2018 年留长发至今，已过肩快及腰，喜欢听摇滚乐 / 新金属 / 核；

家庭主厨，小红书的潮汕美食博主 @底迪 ，擅长粤菜和潮汕菜。

虽然有点变化，但不多，什么都可以变，但热爱的东西不变。

稳定了 1/5 个世纪的性格

情绪和性格方面，这十年过得还算乐观，依然是个内向的人，依然独来独往，至于优点和缺点，好像也是维持了至少十年前的状态没啥变化。

优点嘛，想了想，比如：会做饭、喜欢做家务、能坚持文字阅读、情绪还算稳定、做事还算细心…… 都是一些独处的能力？好像也都是一些只要是个人都可以学会的东西……

缺点倒是挺多的，比如：不会抽烟、不会喝酒、不会打牌、不会打麻将、不会桌游、不会唱歌、不会打篮球、不会踢足球、不会炒股、不爱八卦、不会开摩托、不会骑电动车、不会开车…… 相对于新时代对一个普通人的要求，我好像什么都不会，可以说社交方面还真的就蛮需要这些技能的。

要学的话貌似也不难，但主要的阻力是自己不愿意，因为做自己不喜欢的事情很痛苦，就拿开车来说，因为从小家里很穷，出行只有自行车，后来有机会坐车的时候都是从潮州开到广州的大巴车，每次都几乎坐到吐，很害怕车的味道，打车有时候也会遇到那种味道，说不上来是什么味，很难受，心理阴影面积很大，所以一直到现在，我都不喜欢坐车，每次坐进车里还没开就会有一种心理排斥。

洪金宝在《奇谋妙计五福星》里的这段台词，简直就是为我量身定做，笑死。

做自己喜欢的工作

很多人转码农都是基于 “混口饭吃” ，说直白点就是趁年轻多赚点，仅此而已，但我是在考虑很久尝试很久确定自己是真的喜欢才转行的。

在做产品运营的时候，最早是为了在拿不到排期的时候能解决自己的需求上线而尝试自己实现，写着写着感觉做前端挺有意思的，又从前端慢慢接触到其它更多的领域，读了很多计算机大佬的故事，并且也看着很多前辈都是五六十岁还在写代码，感受到如果真的喜欢，这就是一个能玩一辈子的事情，计算机的世界太广阔了，想怎么玩都行。

最重要的是：这一行很适合我这种独来独往的内向人士，不像以前要出差、要去接触各种玩家、媒体，反正只要自己乐意，可以从起床直接写代码写到睡觉，不用跟什么人打交道！

我在知乎上回答过两个关于职业咨询的问题，有几段话虽然是对提问者说的话，但实际上也是在人生十字路口的时候会对自己说的话。

一个是关于是否要转岗的：

在 “大转岗” 这个事情上面，单纯的喜欢是远远不够的，如果想在某个岗位走的更深更远，靠着一份 “喜欢” ，是支撑不了你很多年的，你至少需要上升到 “热爱” 这个层次。

我这里的 “大转岗” 是指 “产品转运营” / “运营转技术” 这种直接脱离原来核心能力的转岗； “小转岗” 一般是 “社区运营转直播运营” / “内容运营转新媒体运营” 这种原来的经验还可以大幅度复用的转岗。

“小转岗” 很正常，但是 “大转岗” ，大部分人其实都不会有很多次大转岗的机会，因为：虽然说种一棵树最好时间是十年前，其次是现在，但是这棵树要从树苗长成大树，它是需要时间的，如果没有足够的热爱去支撑你不断提升自己，那么很可能两三年就觉得又想换个岗位做一下，等到你毕业 10 年了，人家在那个岗位上已经是个 10 年经验的大佬，而你在当前的岗位，可能依然是一个只有 2、3 年经验的中级专员或工程师。

就像我喜欢某类型的电影，我可能就是那段时间觉得很喜欢而已（曾经漫威电影必看，到现在压根不看了）；但是我热爱的事情，比如摇滚乐、下厨、养猫，这些事情能够让我从十几岁到现在，还是十年如一日的保持着高度的热情。

—— 领导问我（目前任职前端）愿不愿意转产品?

另一个是如何选择适合自己的公司：

这种工作内容拖久了，实际上对你下一份工作所需要的经验沉淀、业绩沉淀，起不到什么帮助，工作越久，需要的工作经验是深耕，而不是广而不精。

目前你还有一个优势是，已经回到了家乡，哪怕今年疫情影响工作比较难找，但是家在身边，总归比其他人能撑得住，我认真建议你先别着急接一些奇奇怪怪的 Offer ，好好考虑一下自己的兴趣和未来的发展方向。

做自己喜欢的事情是最好，哪怕有时加班到半夜，也会是一种目标接近完成的兴奋感，而不是说好烦啊怎么还没搞完我不想上班了的丧。

—— 网易外包岗和小公司的正式员工该选哪个？

特别是那句 “哪怕有时加班到半夜，也会是一种目标接近完成的兴奋感” ，最近一年在狂赶 fnOS 的需求时，总会在开发完的时候冒出来和我击掌。

影响过我的人

这十年来影响过我帮助过我的人很多，展示一个 Acknowledgement 在这里肯定放不下哈哈哈哈，我主要单独提一下对我在 “入门、成长、坚持” 这三个阶段影响比较大的人，没有提及的大佬们请不要介意，我一样心存感激！

入门阶段

“入门” 阶段的影响力应该属于初代淫贼三人组…… （后面不同时期有不同的淫贼 N 人组… ）

插个词语释义： “淫贼” 是我对好友们的昵称，代表这个人人品端正、性格随和、乐观有趣、落落大方、有自己的独立人格、开得起玩笑、不会过于严肃、在一定程度上聊得来，是一个非常褒义的词语哈哈哈！

三人组分别是：产品大佬吴庸吴老师、技术大佬振权（网名 phpbug ）和家辉（是的，真的姓张！）。

2014 年那会因为一些项目合作，和他们仨对接很频繁，也因为他们当时都有自己的独立博客，在他们的影响下我也尝试自己搞了起来。

在此之前完全没搞过自己的网站哈哈哈哈，也是第一次购买了自己的域名，学着很多技术大佬那样，实名制走江湖（像：阮一峰 ruanyifeng.com 、张鑫旭 zhangxinxu.com ），所以也用了自己的姓名拼音注册了域名，幸亏当时用了自己的名字，不然这些年各种中二的网名改来改去都不知道该叫什么了……

还记得最早是用新浪的 SAE 托管的，后来越来越慢，而且免费用户极度不友好，就逐步迁移到阿里云用到现在（在 2018 年迁移后的第一篇博客 《 世界，您好！ 》 有说过这个事情，刚看了一下，当时竟然还是用 Windows 做的服务…… 不堪回首），说来这次迁移可以说是绝对正确的选择，现在工作的服务也都是阿里云的，契合度 100% 。

成长阶段

在成长阶段里，前端大佬丰神对我的影响很大，除了请教过他不少问题外，他在我刚起步的时候对我说过一句话印象特别深刻，那就是 “不要只学会实现功能，还要了解实现原理” 。

那个时候我刚好处于 ”想实现 A 功能，就去搜包含 A 功能的 demo ，改改代码放到自己的网页上跑起来“ 的阶段，功能实现是实现了，但不知道为什么就实现了，所谓的代码能跑就行。

这句话在自学的过程中对我影响很大，当了解了实现原理之后，就会懂得如何举一反三去做更多的东西！哪怕没有亲自写过的也能知道个大概，以后遇到类似功能也有印象应该往哪个方向去查资料。

另外还有小毅 @chawyehsu ，当我还在用 jQuery 写 HTML 页面的时候，跟我分享了 Vue.js ，也就从那个时候开始慢慢知道了还有 Node.js 、 Webpack 等前端工程化的一些东西，以及来自 React / Vue 在当年完全没接触过的全新开发模式，还有不知道从哪年开始被他影响了开始在 GitHub 上活跃，在开源上真的学到了很多在公司里学不到的东西！（Btw: 他在 GitHub 也很活跃，熟悉很多开发语言，目前休息 ing ，年后有公司 OR 猎头挖人的话可以联系聊聊！）。

坚持阶段

这一点我要感谢从小影响我长大的黄家驹先生和 Beyond 乐队，他们的歌给人努力、乐观、坚强的感染力，并且人生真的没有污点、一直言行一致地传达着积极向上的精神。

就像《Beyond 日记之莫欺少年穷》的这个片段（右下角可以先暂停 BGM 再看）。

还有之前某天在凌晨三点多的时候，想起小时候看过的一个香港广告《生有限 活无限》，凭着记忆里的画面关键词搜了出来，竟然是 2000 年拍的，可以说是最喜欢的一个广告片，整整 24 年都没有忘记里面的画面和文案。

开源社区

回来讲讲我的 2024 年，虽然这一年很忙，但还是偶尔在 GitHub 上提交一些有的没的，毕竟之前开源的项目也有一些用户反馈，时不时跟进一下，另外主要就是对博客做了一次改版，这一波也是贡献了不少活跃度在里面（截图生成自 GitHub Contributions ）。

前段时间还在博客上线了一个 开源项目 的栏目，记录了一些由我创建或维护的项目，虽然没有大型项目，但有一些教程或者工具的受欢迎程度还可以，如果觉得不错，欢迎点个 Star 支持一下！

主力项目

其他的事情今年没什么时间搞，主力还是在开发公司的 飞牛 fnOS 的 Web 生态，可能很多朋友在公测期间就已经用上了，我家里的 NAS 也是装着我们的系统，用自己开发的作品影响着自己的生活！

如果不了解 NAS ，也可以看我之前写的《 千元预算组装入门 NAS 设备 分享 NAS 的硬件基础知识 》 一文。

刚好放假前用 git-fame 跑了一下代码贡献度，发现我竟然是贡献度最高的，有点惊喜啊哈哈！不过作为 Core Team 的第一批成员，确实参与到了很多需求里，也学到了很多东西，感谢团队！

这个产品 2025 年会正式上线，到时候欢迎大家来体验！

关于 2024 年和独立博客的十周年回顾，就写到这里吧，祝大家新年快乐！

反馈在 RSS 聚合软件里提示订阅报错了，我自己也尝试了确实不行，奇了怪了！

报错截图和信息

在浏览器直接访问 XML ，发现 Network 里 Failed 了，控制台还报了个错误信息：

net::ERR_INCOMPLETE_CHUNKED_ENCODING 200 (OK)

截图如下：

这个报错有点眼熟啊！想起前段时间给博客加搜索功能的时候，一开始想做全文搜索，结果部署后也遇到类似的报错，本地 build 完预览没事，线上就跪了。

但那次因为是把所有文章都处理到一个 JSON 文件里，但因为文章里有很多代码块等内容，引起问题的原因比较多，例如可能破坏了数据结构、文件本身也很大，所以做搜索的时候最后决定去掉全文，改成了只搜标题，解决了当时遇到的问题，但没想到在 RSS 这里还是遇到类似的情况了。

那会还在本地 Docker 部署对比了，但本地也正常，愣是没怀疑到线上多了一层 Nginx 可能是个坑。

解决思路

由于对 Nginx 并没有过多的深入使用，常年处于基础的转发配置阶段，所以直接请教 GPT 帮我解决。

调整 Nginx 的配置

原来的配置是这样子，比较早期的默认配置：

server_names_hash_bucket_size 128;
client_header_buffer_size 32k;
large_client_header_buffers 4 32k;
client_max_body_size 50m;

sendfile   on;
tcp_nopush on;

keepalive_timeout 60;

tcp_nodelay on;

fastcgi_connect_timeout 300;
fastcgi_send_timeout 300;
fastcgi_read_timeout 300;
fastcgi_buffer_size 64k;
fastcgi_buffers 4 64k;
fastcgi_busy_buffers_size 128k;
fastcgi_temp_file_write_size 256k;

按照 GPT 的描述， proxy_buffer_size 、 proxy_buffers 和 proxy_busy_buffers_size 这些参数用于调整代理缓冲区的大小， fastcgi_buffer_size 、 fastcgi_buffers 和 fastcgi_busy_buffers_size 这些参数用于调整 FastCGI 缓冲区的大小，另外还建议我新增 Proxy 缓冲区相关配置。

打开 nginx.conf 文件，修改配置如下：

fastcgi_connect_timeout 300;
fastcgi_send_timeout 300;
fastcgi_read_timeout 300;
-fastcgi_buffer_size 64k;
+fastcgi_buffer_size 128k;
-fastcgi_buffers 4 64k;
+fastcgi_buffers 4 128k;
-fastcgi_busy_buffers_size 128k;
+fastcgi_busy_buffers_size 256k;
-fastcgi_temp_file_write_size 256k;
+fastcgi_temp_file_write_size 512k;

+proxy_buffer_size 128k;
+proxy_buffers 8 128k;
+proxy_busy_buffers_size 256k;
+proxy_temp_file_write_size 512k;

调整完这些配置后，重启 Nginx 服务以应用更改。

sudo nginx -s reload

现在确实解决了，成功订阅！

在博客里， Markdown Parser 的整个工作流程都是自己管理的，包括不同结果的输出，例如：提供给 RSS 订阅用的 HTML ，提供给列表和搜索用的 Metadata ，以及提供给详情页作为 React 组件渲染内容用的 JSX ，这些过程并不算复杂，事实上进展确实是很顺利，但是在我以为即将大功告成之际，突然发现渲染出来的内容少了一个东西：我的视频呢？

改版前的表现

改版之前是使用 Markdown-it 作为技术栈， Markdown 代码与 HTML 代码的相处非常和谐，对于没有 Markdown 原生语法支持的 HTML 标签，都可以直接编写 HTML 代码进行渲染，内嵌视频最初就是这样子实现的。

像这样，在 Markdown 里直接编写 HTML 代码，即可直接输出 HTML 。

<video 
  src="https://cdn.chengpeiquan.com/video/my-cats-in-mountain-view-room.mp4" 
  poster="https://cdn.chengpeiquan.com/img/2022/12/20221231235941.jpg?x-oss-process=image/interlace,1"
  title="山景房里的三只猫"
  controls
  preload="auto"
/>

但改版后，原本应该渲染为视频的地方，都只剩下一个 <p></p> 标签，很明显是在 Markdown 代码转换过程中被过滤了。

理解 Unified 的工作流程

像我这种 Parser 流程比较长，中间处理环节还是动态变化的情况，很怕这些奇怪的问题，但还好 Unified 的设计非常清晰，先了解一下实现原理，更方便找到问题的原因。上面提到了 Unified 包含了 Remark 和 Rehype 两个系列的工作流，因为在 Unified 生态的工作过程中，都是基于 AST 语法树工作，可以简单地理解为：

1. 先由 Remark 负责把 Markdown 文件的内容转为 MDAST ，在这个过程中所有代码都是围绕 Markdown 工作
2. 再通过中间插件 remark-rehype ，把 MDAST 转为 HAST
3. 最终由 Rehype 处理 HAST ，自此阶段开始，所有工作都是围绕 HTML 展开，最终输出什么样的结果也是在这个阶段处理

以上流程可以反过来，也就是先处理 HTML 再还原为 Markdown ，如果是这种流程，中间插件需要更换为 rehype-remark 。

名词解释：

MDAST —— Markdown Abstract Syntax Tree ， Markdown 抽象语法树

HAST —— Hypertext Abstract Syntax Tree ，超文本抽象语法树

问题的排查

了解了工作流程，就可以分三个阶段排查问题了，要么就是在 Remark 环节把 HTML 代码屏蔽了，要么就是 Rehype 环节有问题，要么就是中间的 AST 转换抛弃了这部分代码。

此时 Parser 里的处理器插件是这么启用的：

const processor = unified()
  .use(remarkPlugins) // Markdown to MDAST
  .use(remarkRehypePlugins) // MDAST to HAST
  .use(rehypePlugins) // HAST to HTML
  .use(reactPlugins) // HTML to JSX

const file = await processor.process(markdown)

这里的每一个 Plugins 变量都是一个数组，会根据我的构建场景动态启用插件（相关源码见：core/parser ），例如：

import remarkParse from 'remark-parse'
import remarkGfm from 'remark-gfm'
import remarkStringify from 'remark-stringify'
import { type PluggableList } from 'unified'

const remarkPlugins: PluggableList = [
  [remarkParse], // e.g. [plugin, pluginOptions]
  [remarkGfm],
  [remarkStringify],
]

因此先仅启用 remarkPlugins ，发现一切正常，继续启用 remarkRehypePlugins ，就出问题了， Markdown 里的 <video /> 标签被过滤了。

所以我在 remark-rehype 的文档里找到了关于 HTML 标签过滤的说明：

因为在 markdown 中支持 HTML 是一项繁重的任务（性能和包大小） ，而且并不总是需要的，要同时使用两者，您还必须配置 allowDangerousHtml: true 选项。 —— 详见 When should I use this?

解决方案

原因被定位到了就很好解决，目前是找到了这些解决方案，可以根据需要处理。

开启 allowDangerousHtml

根据 remark-rehype 的文档，仅需开启该选项即可支持将 Markdown 里的 HTML 代码作为半标准节点嵌入 HAST 中 raw 。

import remarkRehype from 'remark-rehype'
import { type PluggableList } from 'unified'

const remarkRehypePlugins: PluggableList = [
  [remarkRehype, { allowDangerousHtml: true }],
]

注意：除了该插件需要开启该选项之外，像我的博客还使用了 rehype-stringify 插件，它也需要一起开启该选项。

由于我还使用了 rehype-sanitize 用于对 HTML 内容的清理，因此仅开启该选项在我的博客里并不能直接达到目的，还要在 Sanitize 进行放行，并且平时写 React 组件的习惯上，我对 dangerouslySetInnerHTML 的使用非常克制，有一些代码洁癖让我不喜欢这个方案，因此我放弃了它。

将 Raw HTML 转为 HAST

在 remark-rehype 的文档里，描述 allowDangerousHtml 部分提及到了另外一个插件： rehype-raw 。

这个插件很适合希望支持渲染嵌入在 Markdown 里的 HTML（需要传递 allowDangerousHtml: true 给 remark-rehype ）,它可以获取 Markdown 里的 HTML 字符串并将它们作为实际节点包含到 HAST 中。

在开启 allowDangerousHtml 选项时， Markdown 里的 HTML 代码仅作为半标准节点嵌入 HAST 中 raw 属性，但配合这个插件，可以将原始的 HTML 字符串解析为标准的 HAST 节点。

处理过程需要依赖一个完整的 HTML 解析器（详见 parse5 ），它将完全按照浏览器解析的方式重新创建抽象语法树，同时保持原始数据和位置信息完好无损。

注意在使用过程中的插件顺序：

import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import rehypeRaw from 'rehype-raw'
import { type PluggableList } from 'unified'

const remarkRehypePlugins: PluggableList = [
  [remarkRehype, { allowDangerousHtml: true }],
]

const rehypePlugins: PluggableList = [
  [rehypeStringify, { allowDangerousHtml: true }],
  [rehypeRaw],
]

这个方案处理过程比较繁重，但这是支持不受信任内容的唯一方法，除非类似那种内容完全由用户提交的场景，否则在内容可控的场景下，都不推荐使用这个方案。

使用 Markdown 图片语法

这是一个最轻巧的解决方案，几乎没有多余的处理成本。

因为我的博客文章详情页最终是通过 JSX 进行渲染（可参考 markup/renderer ），因此完整的处理过程是：Markdown > MDAST > HAST > HTML > JSX ，在最后一个环节使用 rehype-react 的时候，可以将 HTML 代码转换为 React 组件需要的 JSX 代码。

import rehypeReact, { type Options as RehypeReactOptions } from 'rehype-react'
import { a, img } from './components'
import { Fragment, jsx as _jsx, jsxs as _jsxs } from 'react/jsx-runtime'
import { type PluggableList } from 'unified'

const components = {
  a, // e.g. `<a />` --> Next.js `<Link />`
  img, // e.g. `<img />` --> Next.js `<Image />`
} as unknown as RehypeReactOptions['components']

const rehypeReactOptions = {
  Fragment,
  components, // e.g. Record<tagName, componentName>
  ignoreInvalidStyle: true,
  jsx,
  jsxs,
  passKeys: true,
  passNode: true,
  development: false,
} satisfies RehypeReactOptions

const reactPlugins: PluggableList = [[rehypeReact, rehypeReactOptions]]

所以我想到了一个方案，使用 Markdown 内置的图片语法，将视频链接放在原本需要放图片链接的位置，然后在转 JSX 的过程中，判断 URL 结尾的扩展名将视频 URL 分配给 Video 组件。

![山景房里的三只猫](https://cdn.chengpeiquan.com/video/my-cats-in-mountain-view-room.mp4)

// components.tsx

const video = async (props: React.VideoHTMLAttributes<HTMLVideoElement>) => {
  // 组件里的其它逻辑
  // ...

  return <video {...props} />
}

export const img = async (props: React.ImgHTMLAttributes<HTMLImageElement>) => {
  // 判断常用的视频文件扩展名，将其转发给视频组件渲染
  if (props?.src?.endsWith('.mp4')) {
    return <video {...props} />
  }

  // 组件里的其它逻辑
  // ...

  return <img {...props} />
}

事实上在文章详情里实现很完美，但我考虑到了 RSS 订阅源里的 HTML 代码并没有得到解决，并且这种方式无法配置视频的 poster 属性，所以这个方案也被我放弃了。

使用 Markdown 自定义指令

这个方案是在 GitHub Remarkjs Discussions 里搜索时找到了几个讨论，提供了很棒的灵感！

• Embed videos in markdown? #1043
• displaying video by link in react-markdown #957
• What can remark actually do / how to display videos in markdown? #557
• How to type a custom plugin on project? #747

Remark 提供了这方面的插件支持，仅需安装 remark-directive 插件，这是对 Markdown 指令语法提案 的实现（这个提案很有意思，值得阅读！），可以使用和 Markdown 十分接近的语法实现一些自定义功能。

看到这里的读者应该不会陌生，很多知名的静态生成器项目都支持自定义指令，例如：

• 告示 - Docusaurus
• 自定义容器 - VitePress

最终实现方案

简单说一下实现方案，最终是通过编写一个 Remark 插件实现自定义指令，以 :::video 的语法，在 Markdown 内容里配置视频的 src 、 poster 、 title 属性。

源码现在维护在 @blackwork/machine/remark-video ，这里贴的代码在未来可能会有变化。

所需的依赖

先安装依赖，由于不需要在运行时使用，所以统一安装到 devDependencies 里。

pnpm add -D remark-directive unist-util-visit @types/mdast

这些插件的作用：

设计时的想法

考虑到需要配置的参数如 src 和 poster 的 URL 都比较长，用 leafDirective 语法会比较难维护，因此选择了 containerDirective 语法，按照约定，从上往下分为三行内容，分别是 src 、 poster 以及 title ：

:::video
https://example.com/video-src.mp4
https://example.com/video-poster.jpg
A video title
:::

其他的视频播放器属性，由指令插件统一管理，因此不需要在 Markdown 里自定义配置。

编写指令插件

按照 README 的例子，很快就能编写一个自定义插件了，这里就不赘述具体的过程，看代码和注释即可。

import { type Root } from 'mdast'
import { visit } from 'unist-util-visit'
import { isArray, isObject, isString } from '@bassist/utils'

// For the `src` and `poster` attributes
interface LinkNode {
  type: 'link'
  url: string
  children?: unknown[]
  [key: string]: unknown
}

// For the `title` attribute
interface TextNode {
  type: 'text'
  value: string
  [key: string]: unknown
}

interface VideoDirectiveNodeChildren {
  children: (TextNode | LinkNode | unknown)[]
}

interface VideoDirectiveNode {
  type: 'containerDirective'
  name: 'video'
  children: VideoDirectiveNodeChildren[]
  [key: string]: unknown
}

interface HyperScriptData {
  hName?: string
  hProperties?: {
    [key: string]: unknown
  }
  [key: string]: unknown
}

/**
 * With container directive
 *
 * @example
 *   ;```md
 *   :::video
 *   src
 *   poster
 *   title
 *   :::
 *   ```
 */
const isVideoNode = (i: unknown): i is VideoDirectiveNode => {
  if (!isObject(i)) return false
  const children = i?.children?.[0]?.children
  return (
    i.type === 'containerDirective' &&
    i.name === 'video' &&
    isArray(children) &&
    children.length > 0
  )
}

const isLinkNode = (i: unknown): i is LinkNode => {
  return isObject(i) && i.type === 'link' && isString(i.url) && !!i.url
}

const isTextNode = (i: unknown): i is TextNode => {
  return isObject(i) && i.type === 'text' && isString(i.value) && !!i.value
}

const isValidChildNode = (i: unknown) => isLinkNode(i) || isTextNode(i)

/**
 * I have customized a compilation process in Markdown Parser, so not all HTML
 * codes are allowed to be rendered.
 *
 * When Markdown is being converted to AST, many HTML tags will be discarded,
 * and the same is true for Video.
 *
 * In order to uniformly implement custom rendering content, this plugin
 * implements the ability of `video` directive.
 *
 * One more important thing, since rehype-sanitize is enabled, remember to
 * configure the options to allow rendering of video tags and attributes.
 *
 * @example
 *   Enter the following into the markdown file:
 *
 *   ```md
 *   :::video
 *   https://example.com/video-src.mp4
 *   https://example.com/video-poster.jpg
 *   A video title
 *   :::
 *   ```
 *
 *   Compile and output a Video tag:
 *
 *   ```html
 *   <video
 *   src="https://example.com/video-src.mp4"
 *   poster="https://example.com/video-poster.jpg"
 *   title="Hello World"
 *   />
 *   ```
 *
 * @returns Transformer
 */
const remarkVideo = () => {
  return (tree: Root) => {
    // Prevents the following judgment from being inferred as never
    visit(tree, (node: unknown) => {
      if (!isVideoNode(node)) return

      const [srcNode, posterNode, titleNode] = node.children[0].children
        .map((i) => {
          if (isLinkNode(i)) return i
          if (isTextNode(i)) {
            i.value = i.value.replace(/\n/g, '').trim()
            if (i.value) return i
          }
          return undefined
        })
        .filter(isValidChildNode)

      const src = srcNode.url
      const poster = posterNode.url
      const title = titleNode.value

      const data = (node.data || (node.data = {})) as HyperScriptData
      data.hName = 'video'
      data.hProperties = {
        src,
        poster,
        title,
        controls: true,
        preload: 'auto',
        className: 'w-full aspect-video rounded-lg',
      }
    })
  }
}

export default remarkVideo

启用插件

在我的博客项目里，是在 core/parser 里启用插件（也就是最终提供给 unified().use() 使用 ），在使用的过程中，如果启用了另外一个 rehype-sanitize 插件，还需要在该插件的选项里配置 tagNames 和 attributes 的白名单列表。

import remarkDirective from 'remark-directive'
import remarkVideo from './plugins/remark-video'
import { type PluggableList } from 'unified'

const remarkPlugins: PluggableList = [
  [remarkParse],
  [remarkDirective],
  [remarkVideo],
]

const rehypePlugins: PluggableList = [
  // ...
  [
    rehypeSanitize,
    {
      // No need `user-content-` prefix
      clobberPrefix: '',
      // https://github.com/syntax-tree/hast-util-sanitize#tagnames
      tagNames: [...toArray(defaultSchema.tagNames), 'video'],
      // https://github.com/syntax-tree/hast-util-sanitize#attributes
      attributes: {
        ...(defaultSchema.attributes || {}),
        video: ['src', 'poster', 'controls', 'preload', 'className'],
      },
    },
  ],
  // ...
]

// ...

最终结果

这就是这段 Markdown 指令渲染出来的效果（当然，不包括下面的标题展示，那是我另外包裹了一层 figure 标签，详见 parser/components ，在转换为 JSX 的时候处理的）。

:::video
https://cdn.chengpeiquan.com/video/my-cats-in-mountain-view-room.mp4
https://cdn.chengpeiquan.com/img/2022/12/20221231235941.jpg?x-oss-process=image/interlace,1
山景房里的三只猫
:::

当然在教程里还是主动引导读者自己从零开始创建这个 Hello 项目，这也带来了这个假期遇到的一个读者反馈的问题。

事情起因

前几天在 GitHub Issue 的评论区，有位读者和我反馈说在运行 npm run build 时出现类似下方的报错，无法正确编译（见 #193 (comment) ）。

触发错误日志

遇到反馈的问题，首先是要先复现问题，于是先把仓库里的演示项目拉下来跑了一下，依然可以正常运行，但因为 “自己的代码自己清楚” ，马上联想到一个区别，就是读者自己创建的项目，依赖可能都是最新版，而我的演示项目由于 package.json 和 package-lock.json 里的版本号已有指定，因此 node_modules 下安装好的依赖可能并不完全一样，所以在演示仓库的项目里，这个错误没有被触发。

因此我把 node_modules 和 package-lock.json 文件删除，再重新安装依赖，确实，现在演示项目也无法通过编译了，还好日志很清晰，报错是来自 node_modules/@types/node/globals.d.ts 这个文件：

➜  hello-node git:(main) ✗ npm run build

> @learning-vue3/node@1.0.0 build
> tsc src/ts/index.ts --outDir dist --target es6

node_modules/@types/node/globals.d.ts:6:76 - error TS2792: Cannot find module 'undici-types'. Did you mean to set the 'moduleResolution' option to 'node', or to add aliases to the 'paths' option?

6 type _Request = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").Request;
                                                                             ~~~~~~~~~~~~~~

node_modules/@types/node/globals.d.ts:7:77 - error TS2792: Cannot find module 'undici-types'. Did you mean to set the 'moduleResolution' option to 'node', or to add aliases to the 'paths' option?

7 type _Response = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").Response;
                                                                              ~~~~~~~~~~~~~~
// ...

分析错误日志

由于这个项目是很入门的演示项目，主要为了演示 Common JS 模块和 ES Module 模块的开发，以及一些 TypeScript 语法的入门，并没有涉及到 Node.js API 的操作，因此也没有主动去安装 @types/node 这个包。

这里顺便补充个说明： @types/node 包主要是为 TypeScript 提供 Node.js API 的类型定义，如果在项目里调用了 Node.js 的 API ，则需要显式安装它，使 TypeScript 可以识别到这些 API 。

所以 @types/node 这个包只能是第三方依赖带进来一并被安装的，为了方便排查，重新克隆了一个演示项目的原版，并通过 npm list @types/node 查看可以正常 build 时的依赖版本号，以及是哪个包引入的这个依赖。

➜  hello-node-original git:(main) ✗ npm list @types/node

@learning-vue3/node@1.0.0 /Users/chengpeiquan/Documents/projects/demo/h2
└─┬ ts-node@10.9.1
  └── @types/node@18.11.0

此时正常 build 的 @types/node 版本号是 18.11.0 ，是从 ts-node 引入的。

同样的命令在有问题的项目下运行，得到不同的版本号 20.12.5 。

➜  hello-node git:(main) ✗ npm list @types/node

@learning-vue3/node@1.0.0 /Users/chengpeiquan/Documents/projects/demo/hello-node
└─┬ ts-node@10.9.2
  └── @types/node@20.12.5

查看项目 node_modules/ts-node 目录下的 package.json 文件，看到 ts-node 对 @types/node 的依赖版本号是设置为 * 号，也就是通配符（下面是关键信息的列举，非全部）。

{
  "name": "ts-node",
  "version": "10.9.2",
  "peerDependencies": {
    "@types/node": "*"
  }
}

通配符版本号是指允许任何版本的依赖项，会安装最新可用版本，这也是为什么删除了 node_modules 目录和 package-lock.json 文件后，重新安装依赖后版本变化这么大的原因。

关于这个 undici-types 依赖，查看了 @types/node 的 package.json 文件，确实在后面的版本里引入其作为 dependencies 依赖，而之前的版本并没有，在 GitHub 溜达了一圈，原因可能来自 Node.js Undici 的这个 issue ）。

解决问题

原因查明，解决方案就好办了，这里提供两个有效的解决方案。

使用 skipLibCheck 选项

由于 demo 的报错主要来自第三方库的代码检查（ TypeScript 默认会检查所有代码），在实际的项目开发中为了节省编译时间和跳过源码之外的问题报错，通常会启用 skipLibCheck 选项通知 TypeScript 跳过这些依赖库的类型检查（扩展名为 .d.ts 的文件），从而只检查开发者编写的源代码。

这也是为什么写了那么久的 TypeScript 从来没有遇到这种问题的原因，因为在实际项目里一直都是跳过对第三方库的检查啊哈哈哈。

选择这个方案的话，如果是走 CLI 选项编译，可以在命令里添加一个 --skipLibCheck 选项：

// package.json
{
  "scripts": {
    "build": "tsc src/ts/index.ts --outDir dist --target es6 --skipLibCheck"
  }
}

如果是通过 tsconfig.json 配置编译选项，则是添加在 compilerOptions 里：

// tsconfig.json
{
  "compilerOptions": {
    "target": "es6",
    "module": "es6",
    "outDir": "./dist",
    "skipLibCheck": true
  }
}

关于 skipLibCheck 选项 的更多说明可以在 TypeScript 官网文档上查阅。

添加 moduleResolution

除了 skipLibCheck ，还有一个解决方案，还记得错误日志吗？在错误日志里给出了两个解决方案的建议：

Did you mean to set the 'moduleResolution' option to 'node', or to add aliases to the 'paths' option?

由于这是一个第三方库的报错，因此 paths 方案不适用（该方案适合对源码目录下的文件配置 Alias 别名）。

因此可以通过另外一个建议，添加 --moduleResolution 选项。

// package.json
{
  "scripts": {
    "build": "tsc src/ts/index.ts --outDir dist --target es6 --moduleResolution node"
  }
}

也可以成功解决编译问题，同理，也可以在 tsconfig.json 里配置该选项：

// tsconfig.json
{
  "compilerOptions": {
    "target": "es6",
    "module": "es6",
    "outDir": "./dist",
    "moduleResolution": "Node"
  }
}

关于 moduleResolution 选项 的更多说明可以在 TypeScript 官网文档上查阅。

创建模拟器

安装和创建模拟器的过程不赘述了，切记要修改 Hosts 的话，需要模拟器支持 Root ，因此不能选择 Google Play 的 System Image ，否则只能以 Readonly 模式启动模拟器，无法 Root 。

启动可写权限的模拟器

需要通过命令行以 Writable 的模式启动，这个时候不需要开启 Android Studio 了（从 AS 启动的模拟器只有 Readonly 权限）。

# 访问 Android Studio 的模拟器文件夹
cd ~/Library/Android/sdk/emulator/

# 查询所有的模拟器列表
./emulator -list-avds

# 添加可写权限进行启动（这里的 Pixel_7_Pro_API_33 是模拟器名称）
./emulator -avd Pixel_7_Pro_API_33 -writable-system

此时模拟器就运行起来，命令行不要关闭，否则模拟器也会退出。

检查 ADB 启用状态

下一步操作需要通过 adb 命令来执行（关于 ADB 是什么，详细可以见 Android 的官方文档：Android 调试桥 (adb) ），但这里只是想确认它是否存在。

所以直接看 StackOverflow 的操作即可：Set up adb on Mac OS X 。 因为安装 Android Studio 的时候就默认一起装了，所以直接看里面的 “Option 3 - If you already have Android Studio installed” 部分。

注意：我是使用 Oh My Zsh 的 ZSH Shell ，所以配置文件和 StackOverflow 答案里不一样，记得留意自己用的是哪个 Shell 。

echo 'export ANDROID_HOME=/Users/$USER/Library/Android/sdk' >> ~/.zshrc
echo 'export PATH=${PATH}:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools' >> ~/.zshrc
source ~/.zshrc

设置后重启 Terminal ，通过 adb version 命令查看是否启用成功。

adb version

Android Debug Bridge version 1.0.41
Version 34.0.5-10900879
Installed as /Users/chengpeiquan/Library/Android/sdk/platform-tools/adb
Running on Darwin 23.1.0 (arm64)

修改 Hosts

首先确认模拟器编号，通过命令行启动模拟器后，在设置界面可以看到这个 5554 端口号（可能是别的端口）。

或者是通过 Android Studio 启动模拟器，也可以看到端口号。

开始修改 Hosts 啦。

# 通过 ADB 开启 Root 权限
adb root

# 挂载已启动的模拟器文件，这里记得对应模拟器的端口号
adb -s emulator-5554 remount

# 拉取模拟器的文件到桌面，方便修改
adb pull /system/etc/hosts ~/Desktop/hosts

接下来就和之前在 Windows 上修改 Hosts 一样啦，改完后把文件 push 回去。

# 改完后把 hosts 文件 push 回去
adb push ~/Desktop/hosts /system/etc/hosts

# 查看模拟器上的 hosts 文件内容，确认是否修改成功
adb shell cat /etc/hosts

最近跑了 5 年的台式机又感觉配置不太够用了，干脆再换回 Mac ，开心！

在落笔之前想起一个古早笑话……

快六点了，街边卖油条的还没来，我只能拨通他的电话，大哥在那边说：我卖了这么多年的油条了，从来自由自在的，自从遇见你之后，我居然有了上班的感觉。

因为我被催更了哈哈哈哈哈（见 #363 ）。

本来今年的总结第一句话想写 “2023 对我算是比较特殊的一年” ，结果看了一眼去年的回顾，去年也是这么写的…… 那今年再强化一下，改成 “2023 对我是非常特殊的一年” 哈哈哈哈哈哈哈，确实非常特殊的一年，因为经历了很多之前没有经历过的事情。

人生中的第一次失业

去年写总结的时候还是元旦放假前，当时的我对于三天后会发生什么事还一无所知，但也不能说完全一无所知吧，作为一名程序员和刑侦爱好者，上家公司总是结合疫情的风吹草动安排半薪和基薪休假（广州当时其实就海珠区比较严重，其他区域已经放开，我们都不在海珠区，这么喜欢跟风就很不对劲……），所以就已经感觉到前公司当时的运作要崩溃了，只是没想到来的这么快而已。那时候元旦假期刚过完，回去上班第一天前老板就开会说融资失败要执笠了，团队要解散。于是我刚休完元旦假期，上了一天班又继续放假了，当然这次是无薪假期哈哈哈哈。

这是我人生中第一次在没下家的情况下直接失业，既然前面有所感知，为什么没有骑驴找马呢？因为团队里都是我合作了很多年的 Partners ，都是我在网易从 2016 年起陆续认识，一起玩了六七年的 Friends 和 Leader ，包括从网易当时的总监熬不住先跳槽了，我们一起被合并到边缘部门，再一起离职去深圳待了两年，再一起回广州，经历了很多事情，所以表面上连网易在内到当时失业，经历的是三家公司，但实际上一直都在一个团队里（包括前老板以前也是网易的总监，所以那段时间首先想的是有难同当，低谷期总是有的，熬过去就好了）。

过年前失业确实是一个很尴尬的节点，大部分公司在年底是没有招聘计划的，通常会在二月底到三月，等新一年的目标定好才会开始陆续招人，所以那个时候想走内推也没有什么公司有 HC ，也尝试谈了几家创业公司，也没有那么大的团队缺口，都是最多只要一个经验丰富点的来带头开荒就顶天了，盘不下几个人的团队一起去，加上做的事情比较无聊和薪资没谈拢，干脆就等过完年再看机会。

失业期间在干什么

虽然人到中年还是 “三无” 选手（无老婆、无小孩、无房贷压力），但这个时候 “三无” 属性反而使我的抗风险能力达到了 Max ，没有银行给我的还款压力，没有人在旁边唠叨给我精神压力，身边还有三只懂事粘人的猫，所以那段时间心态也比较平稳，工作方面没了事情做就没事情做吧，我自己还有很多事情要搞（在 GitHub 上列了一堆 Projects ），还是忙个不停。

改稿子

那个时候已经和出版社签了合同，准备出版我的书，基于出版规范很多细节要调整，包括不允许出现 “你我他” 这些人称代词，还有很多描述不能口语化，更重要的是保证代码的准确性，平时苦于每天在睡前挤那一两个小时在开夜车改稿，一下子突然有了很多时间让我慢慢改，反而有一种莫名其妙的幸福感…… 每天终于不用那么累了，于是对着 83 页 PDF 的规范手册，几十万字的稿子硬是改完了。

这是后来寄过来校对第二次的清样，哈哈哈哈也别被吓到，单面印刷的所以看起来厚到吓人。

后来这本书在五一期间正式上市了，围绕前端工程化的入门，虽说前端娱乐圈，框架一个又一个，但真正被企业认可的以及基础方面的知识主要还是没太大变化，书的内容的有效性应该可以维持上几年，刚入门前端觉得有需要的同学可以支持一下，感谢您！

相关阅读：我写了一本书《前端工程化：基于 Vue.js 3.0 的设计与实践》 想分享一下它背后的故事

当时给身边好友写的签名本，好羞涩哈哈哈哈哈。

做设计

去年的总结说要对 create-preset 改版，程序至今还是没时间改，倒是对官网先重新设计了一版，还自己鼠绘了个 LOGO ，一年了，自己看起来还是很满意哈哈哈哈哈哈。

还想设计设计自己的新文身，从去年回广州就想加图案，但因为忙也没时间搞，有时间的时候也会胡乱画画找找灵感（红色的是画上去的，最终还是没确定下来，后面也没有时间了就又搁置了，新的一年再看看吧）。

戒掉了网络游戏

当年作为一个资深玩家进的游戏行业，又凭着丰富的游戏经验跳去了网易游戏，没想到有一天我也会不玩网络游戏了，一月份我弃坑了玩了五年的某手游（排名在全区第二），一方面是失业带来的危机感让我觉得继续玩这种时不时要充值的游戏没什么意义，另外一方面是狗策划安排的活动时间实在是过于挤压我为数不多的休息时间，既然花了钱去玩还得不到快乐，那就干脆就不玩了。

在成为 “不抽烟不喝酒不玩游戏” 的好男人一段时间后，有时候很无聊又想玩玩游戏消磨下疲劳，所以现在又像小孩子一样，重新玩起了小时候玩的那些游戏，在模拟器玩 FC 和街机，还有老头滚动条之类的经典单机。

其他的事情

其他事情主要就是改简历和准备面试的事情，失业时间说短不短，说长也不长，刚好过年前到元宵后休息了两个月，二月底内推到现在的这家公司面试通过后就入职了。

新工作是干什么的

现在在一家做 NAS 方向的初创公司做开发，依然是自研团队。目前项目里 C++ 负责 NAS 操作系统的开发，而前端这边是负责把操作系统上的功能实现为界面化的交互（像 Windows / macOS 那样），所以这是一个很重前端的项目，比起传统的 C 端应用或者 B 端一些低代码平台，这个项目我觉得更有意思，也很考验开发者的 TypeScript 功底，目前来了半年多，感觉自己的能力和理解又有了很多提升，当然也离不开身边大佬们的指导和帮助。

产品还在开发中，等上线了我再公开哈哈哈哈

另外还有一个很神奇的缘分，就是现在的老板其实也是我十年前的老板， PP 助手的创始人（早期越狱那个年代的 iOS 用户应该都知道？），我之前也是在 PP 助手团队，后来跟着被收购到了 UC ，再被收购到阿里，被阿里收购后因为阿里部门间合并后的一些后遗症，做的不开心了，我才跳去了网易。

兜兜转转又回来了以前的团队，说不出的兴奋感，因为这里的人也很好，又是一见如故，哪怕多年未见，连我的花名都还记得！虽然离开了一群合作很久的 Partners ，但又回到了另一个很好的 Team ，很开心的一年！现在这里除了以前 PP 的老友，也有后面在 UC 和阿里的同事，虽然有些之前并未谋面，但很快就达成了默契，很合拍的工作节奏！

开源社区

今年还是活跃在 GitHub 上（截图生成自 GitHub Contributions ），可能去年码字太多，今年几乎没写什么文章，一直在敲代码，弥补之前没做的很多事情。

今年敲代码的时间比去年高了不少，晒一下这一年最高敲代码时间的一周，沉浸式敲代码哇哈哈…… （统计数据来自 WakaTime ），我记得有一天敲了 12h 的代码，太早的统计要付费才能看，忘记留个图纪念下。

这么长的敲代码时间倒不是因为公司加班，公司除了版本 DDL 前后会加加班之外，都是六点半下班和双休。

时间方面主要是在这几个地方：

1. 完善自己的工具链（ e.g. 贝斯手 Bassist 系列，还有一些没公开的），把自己常用的工具和配置都集合到一个 Monorepo 管理，避免每次用的时候都要加一堆配置或者重新实现
2. 踩 React 的坑……（下面说）
3. 踩其他技术栈的坑（例如尝试写了一点 Rust …… 还有各种 demo 吧，不是开源，但也都托管在 GitHub 上，所以活跃度就这么来的…… ）

关于踩 React 的坑，去年在总结的新年展望里提到要好好写一下 React ，倒不是说 Vue 不好，相反，真的把主技术栈切到 React 后才发现 Vue 帮开发者做了好多优化，而 React 好多要靠开发者自己处理…… Vue 真是保姆级！

之所以在出了一本 Vue 的书之后，自己写起了 React ，是因为我写多了想换换口味，之前因为公司一直都是 Vue 为主，所以不知不觉也写了得有五年多的 Vue 了，不想像以前读书一样，只偏科数学和物理，文科一塌糊涂，最后总成绩就显得很一般。目前在 Vue 自己也算是有一套自己的最佳实践，平时遇到问题也可以很快排查，而 React 还没有达到这种状态，所以今年主要也在解决自己的偏科问题。

刚好今年换工作后是新团队新项目，涉及到技术选型，新团队的 Partners 都很一致的选择用 React 来写，所以我也很符合个人预期的都在写 React 了。

其他的感慨

首先， AI 真好用哈哈哈，自从 ChatGPT 出来后，工作再也离不开它了，目前主要用它消耗掉很多基础的工作，比如输出单元测试用例、 JSON 转 TypeScript 类型等等，还有遇到问题现在可能不是首选 Google 搜索了，而是在 GPT 先问一下，如果不靠谱再去 Google / StackOverflow / GitHub Issue 找答案。

再一个就是离开网易后很感慨一件事，就是刚转行的时候曾经的产品运营身份让我在技术路上走的蛮辛苦的，有人不认可，有人不信任，在当时确实是一个劣势，毕竟万事开头难，但经过这么多年的热爱和坚持，劣势反过来已经成为了自己的优势。

有一定的产品设计经验、有一定的用户体验优化能力、懂 SEO 懂运营懂用户，往产品工程师方向发展，比做一个纯技术的全栈工程师更现实一些（相对于我这种普通人的认知层面来说的，大佬肯定又有不一样的认知），当然现在托 Node.js 的福，只写 TypeScript 的我也可以写全栈了。

新年愿望

首先希望身体健康啊哈哈哈，距离上一次去医院不知道多少年了，今年才又进了一次医院，做了人生中的第一个小手术，当时耳朵因为细菌感染引起皮脂腺囊肿，去做了个引流手术，第一次动刀子，内心还是比较慌的，还好过程也没有啥感觉，打了个麻药，所以手术过程中还没有文身有感觉（我文身不打麻药！）

其他的还是先把原来还没搞完的事情搞起来吧，比如想重构博客一年多了，结果因为这个那个事情，一直拖着没处理，一下子距离上一次重构都已经三年了，真是见鬼啊哈哈哈哈时间怎么这么快！！！

都记录在 GitHub 的 Projects 里管理了，等做到了再说吧，不立那么多 Flag ，免得一年又一年说了又不做哈哈哈哈哈。

谢谢阅读！

先补一个 2025 的更新，回想当时把闲置的猫航空箱用来装 NAS 真是明智，在 24 年国庆的时候又搞了个五盘位的硬盘柜，还是很能装！目前的搭配是：小主机 + 外接硬盘柜 搭配 飞牛私有云 fnOS NAS 系统，主要搞下影视和相册，个人体验非常好！

目前自组 NAS 来说，免费并且简单上手、日程使用稳定等角度来说，飞牛的 NAS 系统是很不错的，可以在 飞牛官网下载 ，自己用 USB 烧个引导盘就能装，或者用 PVE 虚拟机跑也没问题。

最终组装方案

好了，看完现在最新的配置，回到最早的第一版，这是我当时的千元配置的最终方案。

毕竟第一次玩 NAS ，并且要存储的数据也不是多到特别多，所以出于在预算范围内的一个控制，还是尽量控制在一千块钱不要超出太多，最终我自己的方案如下：

总价 ￥ 1161.8 ，在 618 前买的，部分配件还进行了保价退了点钱，迷你主机不需要风扇降温，而且送了电源适配器，所以很多配件的钱都省了下来。里面之所以有多一个固态硬盘是因为迷你主机支持插一个 mSATA 的 SSD ，刚好现在 SSD 价格又不贵，内置一个 SSD 用来装系统，然后机械硬盘就可以完全当存储盘用了。

关于为什么选择硬盘座，是因为我在广州，这边几乎不会有地震，我家三只猫也不会上桌（装监控 4 年了，没有被抓到），加上我有一个闲置的航空箱，我都放到航空箱里面了，安全和稳定性还是很高的，另外一方面是因为我对网口需求不大，有一些迷你主机是四五六个网口，只有两个 USB ，我这个是两个网口，有六个 USB ，用 USB 3.0 来接机械硬盘也不会很慢。

伪装起来还是有模有样的：

弟弟好像发现了里面有什么奇怪的东西：

弟弟一回头：“我的航空箱呢？”

再往前看：“果然是它”

有一说一，航空箱内部的散热还是很不错的，而且空间很大，周围又可以穿线，真的很舒服！

前置知识

继续回来讲初入 NAS 时的一些知识点，刚接触 NAS 的时候最迷茫的应该就是它的概念和用途了，就算了解了它的作用，想采购一个合适的 NAS 设备又会涉及到很多硬件知识。既然选择自己配 NAS 做一个 DIY 玩家，肯定还是需要先熟悉一些前置的硬件知识，否则大可花几千块钱买成品 NAS 了，所以有一些前置知识点还是值得先简单了解一下。

什么是 NAS ?

NAS 全称是 Network Attached Storage ，网络附属存储，关于它的概念可以查看 Wikipedia 词条 。用通俗一点的话来理解，它最直接的用途是当一个自建的云盘服务器，可以存放你的照片、视频、电影资源、重要资料数据等等，而存储介质是属于你自己的，除了自己常用的主机可以访问 NAS 单点存储备份外，还可以作为局域网、广域网共享，家里的其他设备也可以访问到 NAS 上的文件，如果体验过用 AirDrop 从 iPhone 向 Mac 共享文件的便利性，那么通过 NAS 也可以解决 iPhone 和 Windows 共享文件比较麻烦的问题。

借助 NAS 系统，分布式工作环境可以轻松地从任何联网设备访问文件和文件夹，在局域网里可以访问设备的内网 IP 即可访问到 NAS 系统的桌面操作界面，如果有公网 IP 或者做了内网穿透，还可以绑定自己的域名，不在家的时候也可以通过域名访问到家里的 NAS 系统，做到随时随地访问。

因为 NAS 设备充当的是一个服务器的作用，所以在装好系统之后就不需要鼠标键盘和显示器了（系统安装过程中还是需要的，临时拔一下自己其他主机的鼠键和显示器过来用就行）， NAS 系统启动后在局域网内有一个固定的 IP ，使用其他设备（例如台式机、笔记本）去访问这个局域网 IP 即可访问到 NAS 操作系统的桌面界面，这个界面都是以 Web 的形式实现的。

以下是我现在在用的 飞牛 fnOS 系统界面。

为什么要用 NAS ？

在上面提到了 NAS 可以简单的理解为一个自建的云盘，存储介质都属于自己，数据的管理也都是自己，这一点有什么好处呢？

如果你在网上冲浪比较久，应该早就知道很多平台哪怕被用户信任了十几年，还是会因为盈利问题或者不可抗拒的原因关闭下线（例如 国内某巨头的相册 、 国内某巨头的云盘），虽然关停前会有一段时间让用户可以把自己的东西下载回本地，但有句话说的好，你永远不知道明天和意外哪个先来，可能在关停前短短的保数据阶段，会因为一些意外的事情导致无法及时处理，比如考研备战期间忙的要死根本无暇顾及太多外部杂事，或者是身体原因住院之类的，我自己也在 2020 年也有过挺长时间经历了卧床不能走路的日子，那段时间除了腿脚不便之外，整个人的精力也是前所未有的低谷期，很多时间根本没办法去及时关注。

或者是因为某些原因导致资源再也不能显示，比如我最喜欢的 Beyond 乐队的《长城》、《岁月无声》，三十多年前的摇滚乐了，国内外几亿人都喜欢的歌曲，因为被某些人的过度解读导致永远 404 。

还有南京市民李先生的所有音乐，陪我走过很多次低谷的《你离开了南京，从此没有人和我说话》、《忽然》、《关于郑州的记忆》、《梵高先生》等等正常歌曲也都是不能光明正大的在各大音乐平台搜到（之前保存在云盘里的也被和谐了，还好电脑里有备份）。

数据无价，很多资料本身十分正常，但就是由于某些原因导致无法信任某些平台，像我自己写的 菜谱 虽然主要分享在小红书上，但我也并不信任小红书，不说它会不会在某一天关闭业务，哪怕只是简单到因为审核到不和谐的内容然后就把我号封了，我写的东西也就没了（已经收到过系统通知说出现不适合推送的内容，所以本条笔记不做曝光，但不会告诉我要怎么修改），所以我才自己同步了一份数据到我自己的 GitHub 和自己的数据库做多端备份。

当然 NAS 除了做基础的存储，很多服务还可以自己配置用起来，比如现在各个平台都要会员，优酷开一个、爱奇艺开一个，网易云音乐开一个， QQ 音乐开一个，每个平台都有自己专属版权的资源，开多个平台的会员，这里也是很大的成本支出。

所以需不需要 NAS ，最终还是看个人需求，对我自己来说，有一个用来备份重要数据的 NAS 还是很有用的。

主要配件

组 NAS 有很多种方案，最简单的是购买 NAS 厂商提供的成品，国内的像群晖、威联通、绿联、铁威马、极空间等等，优点就是直接购买成品，买回来也是开箱即用，缺点就是溢价太高，相比自己组装，随便一个基础型号都几千块钱，对于不是重度 NAS 用户来说，实在太贵了。

所以我选择了自己组装硬件来做一个 NAS ，方案我是准备了三套，就是放在最后面介绍的 搭配方案 。当然有旧电脑也是可以用来装 NAS 系统当 NAS 设备用的。

一般来说硬盘都是要单独选购，而其他的如 CPU 、主板、机箱等配件通常会放在一起选购，下面先介绍一下主要配件。

CPU

组装 NAS 和组装台式机的过程基本一样，都是优先考虑 CPU ，再去自己搭配主板等其他配件。

NAS 主要还是服务于数据存储的需求，并且一般会 7x24 小时一直开机运行，以方便其他设备随时可以访问，所以更青睐于低功耗的 CPU ，毕竟不是每个人住的地方电费都是 6 毛钱（广州和深圳大部分人的电费都是 1.5 元一度，我也住过这种电费的公寓，动不动就多花不少钱，真的会心痛）。

对我自己来说，我的 NAS 还是存储数据为主，一些视频也没有必要上 4K 之类的（普通的 1080P 也足够我看），所以选择一个低功耗的方案性价比会更高，像赛扬 J4125 / N5105 / N100 都是蛮不错的适合 NAS 的低功耗 CPU ，但对于视频转码有需求的玩家来说，还是得上高性能的 CPU 。

具体有哪些合适的型号可以 Google 一下 NAS 低功耗 CPU ，很多研究的比较深的大佬每年都会分享当下的最佳方案，所以我就不班门弄斧啦！我自己买的时候是看上了赛扬的 J4125 / N5100 / N100 这几个型号，最后是选择了 J4125 ，用下来感觉确实很不错！

主板

主板通常围绕已选好的 CPU 去挑选，常见的主板规格从大到小排序分为 ATX （标准型）、 M-ATX （紧凑型）、 MINI-ITX （迷你型），尺寸越大，可拓展性越高，因此大主板通常适合 DIY 高性能主机，而用于组 NAS 的一般都是用 MINI-ITX 迷你型或者是 M-ATX 紧凑型主板。

但是并非任意主板都可以和任意 CPU 配对，主板上面有 “芯片组” 来适配指定某些型号的 CPU ，芯片组是主板的核心，一块主板能提供什么样的功能、可以支持哪些处理器都是由芯片组所决定的，所以选错了会出现不兼容的情况。

板 U 关系对新玩家来说可能比较复杂，所以我才建议先选好合适的 CPU ，然后选购主板时就可以用 CPU 的关键词去找，例如 “J4125 ITX 主板” 这样的关键词去搜符合需求的主板。

确定好主板之后，其他配件也会跟着主板走，例如内存条、网卡、 USB 等插口都是和主板有关系，这也是为什么讲完 CPU 会先说主板，因为它们有一个搭配顺序。

内存条

内存主要有四个注意点：标准、尺寸、大小、频率。

1. 传输标准

传输标准指 Double Data Rate ，双倍数据速率，它的缩写我们比较熟悉，通常结合它是第几代标准，会被称为 DDR3 、 DDR4 、 DDR5 等等，它们之间的差异如下（ DDR2 以前太古老的就不放上来了）。

对目前主流的处理器来说，内存基本都是使用 DDR4 标准，部分比较高性能的处理器可以支持到 DDR5 ，效能更高，但对应的价格也是贵了几个档次，目前来说组 NAS 都是用 DDR4 就足够。

但这也不是说就无脑选 DDR4 完事，因为前面选主板时也说了，内存的插口和主板有关系，因为每一代标准的内存都会设计一个防呆槽，并且每一代的位置都不一样，因此不可以混用，买内存之前切记要看好主板可以插哪一代的内存条。

除了防呆槽位置不同会引起无法正确插上外，内存还有尺寸也要关注，选错尺寸也会导致无法插到主板上。

注： “防呆” 一词最初起源于日本围棋与将棋的术语，这是一种预防矫正的行为约束手段，运用避免产生错误的限制方法，让操作者不需要花费注意力、也不需要经验与专业知识即可直接无误地完成正确的操作。

以前的防呆设计是不兼容的接口物理形状上永远插不进去，常见的 USB 口、网线口、显示器插口都是传统的防呆设计。而现代的防呆设计理念会有更好的用户体验，例如不需要区分正反面的 Type-C ，就是一个新式的防呆设计。

2. 内存尺寸

内存条除了 DDR4 和 DDR5 这些不同的标准带来的防呆槽在不同位置之外，内存条的造型也有一定的区别，通常会分为台式机内存条和笔记本内存条，两者的形状、尺寸、接口、安装方式都不一样，选错了也是无法安装到主板上。

内存条的规格有 DIMM （ Dual Inline Memory Module ，双列直插内存模块）和 SIMM （ Single In-line Memory Module ，单边接触内存模块）， SIMM 属于比较过去式的规格了，目前家用设备基本都是采用 DIMM 规格，并且根据不同的设备还有更多的子规格，常见的有以下两种：

具体的造型差距如下图：

在买内存条的时候可能会看到商品详情写着 DIMM 和 SO-DIMM ，一般 DIMM 默认为 U-DIMM 台式机内存条，而 SO-DIMM 可以默认为笔记本内存条。

具体需要什么尺寸规格的内存，请一定要看好主板上面可以插哪一种再去购买。

3. 内存大小

NAS 对内存的大小需求不高，最最入门级的存储型 NAS 选个 1-2G 内存就足够了（就真的拿来当存储用的，其他啥也不折腾），但如果要组 RAID ，或者跑 Docker 等虚拟化应用，就要视情况加内存了。

不过现在内存的价格也不算太贵，自己如果有打算折腾点东西，那么可以考虑直接买条 8G 的内存，实在不够再加到 16G （加内存之前要看看主板是否可以插多条内存，像 ITX 主板通常最多可以插两条内存）。

4. 内存频率

除了上面几个注意点之外，内存条还有一个参数需要留意，就是频率，单位是 MHz 兆赫，主频越高，内存的读写速度越快，性能越好。

通常 ITX 主板和对应的低压 CPU 都是推荐使用 2400MHz 的内存，所以买的时候最少要买 2400MHz 的内存（具体留意商品详情页的说明）。

如果购买多条内存但是同代不同频，或者是购买的是高于 CPU 支持的频率，那么会自动降频到最低的频率，例如同时使用 DDR4 2400MHz 和 DDR4 2666MHz ，实际使用会降低到 2400MHz 。

硬盘

常用的硬盘主要有这两种（还有一种混合硬盘比较冷门就不提它了）；

固态虽然看起来更好，但目前价格还下不去，因此通常在预算内选购回来的容量也比较小，这也是为什么大部分 Windows 主机都是用一个小容量的 SSD 做系统盘（一般是 C 盘），搭配大容量的 HDD 做存储盘（例如 D 盘、 E 盘）。

组 NAS 一般都是优先考虑存储的，从性价比上来说，存储容量和价格还是推荐购买机械硬盘，另外从某些 “万一” 的情况来说，机械硬盘还可能恢复数据，固态硬盘基本都是直接没了。

因为本次组装 NAS 的主角是机械硬盘，所以单独在 关于机械硬盘 部分详细展开说明，在这里只简单说一下 SSD 固态硬盘，固态硬盘的发展有这两个变化：

• 接口：普遍从 SATA 换成了 NVMe 接口，从速度上来说 SATA 是比 NVMe 慢的
• 造型：从 2.5 英寸的造型缩小到 M.2 规格的迷你外形

很多主板的详情页会说支持 M.2 NVMe SSD ，指的就是 NVMe 接口的迷你固态。

不过需要注意的是，接口和造型这两者并没有直接关系，事实上同时存在 NVMe M.2 SSD 和 SATA M.2 SSD ，并不是说 M.2 就一定指 NVMe SSD 。

另外，实际上 SSD 还有其他类型的接口，例如 mSATA 、 U.2 等等，了解起来又是一匹布那么长，因为不在常用的 NAS 搭配范围内，所以有兴趣可自行了解。

机箱

机箱需要配合主板和硬盘位去考虑，像 ITX 主板通常就选购迷你机箱了，并且搜索关键词通常会搭配这两个配件一起搜，例如 “ITX 四盘位 机箱” 。

这里以某个 NAS 机箱为例，可以看到商品详情会特地注明支持什么类型的主板，还有散热风扇的尺寸

如果购买的是软路由一类的迷你主机来做 NAS （我这次就是选择了迷你主机，具体看后面推荐的方案一和二），那么不买机箱也可以，机械硬盘可以通过硬盘架或者硬盘笼来外置接入。

散热风扇

选购了机箱后，可以看看机箱里面预留的空间选择合适的散热风扇，散热风扇的选择有以下几个方面要注意：

1、尺寸：散热风扇的尺寸非常多，但其实并不太会有选择困难症的问题，因为风扇通常要求与主板的风扇接口大小相匹配，并且在机箱可安装的尺寸范围内，所以根据机箱要求的尺寸去购买即可

2、转速：风扇的转速决定了散热效果和噪音水平，通常转速越高，散热效果越好，但噪音和耗电量也会越大，所以要根据需要选择合适的转速范围

散热风扇一般长这样，外观大同小异，主要区别还是在尺寸上：

总之，要选择适合自己的风扇，应该根据主机机箱的大小、需要散热的硬件组件类型和数量、以及对噪音等因素的要求来进行综合考虑。

电源

通常电源是放在最后选购的，因为几乎每个配件都在耗电，所以电源需要满足全部配件的总功耗，并且尺寸需要符合机箱预留的电源位。

常见的主机电源有 ATX 、 SFX 、 SFX-L 、 Flex 1U 电源，型号对应的体积也是从大到小排序的，自组 NAS 通常会选择 FLEX 小 1U 电源，或者根据主板要求使用 DC 供电（这里的 U 代表 Unit ，1U 等于 1.75 英寸，所以 1U 电源不全都是 FLEX 电源，小 1U 只是国内俗称）。

另外还有一些主板是使用 DC 供电（迷你主机就是），这种就不需要单独买一个电源了，只需要准备一个电源适配器，插到主机上就可以一直供电，这种供电方式在家庭里应该都不陌生，像我的贝斯 DI 盒就是用电源适配器供电的。

参考资料

• NAS 折腾笔记 篇三：选择合适的设备（主板、CPU、内存）
• 芯片组和主板有啥关系？主板型号怎么看？
• CPU 选购基础知识 板 U 怎么搭配？
• NAS 机器的 CPU 跟内存大小对 NAS 机器运行影响有多大？
• SDRAM、DDR、DDR2、DDR3、DDR4 與 DDR5 之間的差異是什麼？
• NVMe vs. M.2 vs. SATA SSD: What’s the difference?
• 为什么消费级的固态硬盘很少有 u.2 接口的?
• ATX/SFX/SFX-L/1U Flex 尺寸区别，电源规格尺寸 v1.0
• PC 电源也有中杯、大杯、特大杯，电源规格简单科普！顺便晒晒新入的海韵 SGX650

关于机械硬盘

在上面 硬盘 部分已经说过 NAS 优先考虑购买机械硬盘，但挑选机械硬盘也不是单纯的一句 “我要机械硬盘” 就完事，选购机械硬盘通常还会遇到这两类问题：

1. 磁记录方式上：分有 CMR （常规磁记录）和 SMR （叠瓦式磁记录）
2. 外观和尺寸上：分有 3.5 英寸（台式机）和 2.5 英寸（笔记本）

另外还有接口和转速要怎么选的小问题。

磁记录区别

常规磁记录（ Conventional Magnetic Recording ，简称 CMR ），俗称 “垂直盘” ，垂直盘的优点是在写入数据的时候不会出现其他多余的操作，写入速度快，硬盘寿命长；缺点是单碟容量略低。

叠瓦式磁记录（ Shingled Magnetic Recording ，简称 SMR ），俗称 “叠瓦盘” ，叠瓦盘的优点是单碟容量更大，造价成本低所以价格也相对便宜（好像也区别不大）；缺点则是当存了太多数据后，即使微小的数据改动，也会反复迁移扇区内的数据，这将严重影响写入速度，并加速盘片和磁头的老化，数据丢失的风险也随之增加。

对于 NAS 用户来说，通常会存储非常多的珍贵数据，在 “数据无价” 四个字面前，叠瓦盘带来的容量和价格优势，相比性能下降和数据丢失风险较高来说并不算值得考虑的点，所以可以看到很多人都说买盘别买叠瓦盘。

所以如果用来做仓库盘，例如存放电影、音乐、文件备份这种平时放着不用、偶尔才选一些出来看，类似这些读写频率不高的场景，可以考虑 SMR 叠瓦盘，否则都应该优先考虑 CMR 垂直盘（如果看到标记了 PMR/CMR 也不用担心， PMR 是 CMR 技术的前身）。

如果商品详情没有标记，也可以看缓存大小来简单判断，一般 64M 缓存或以下的都是 CMR ，而 256M 之类的大缓存硬盘基本上都是 SMR （非绝对，但是相对靠谱）。

尺寸区别

机械硬盘分有 3.5 英寸和 2.5 英寸两种规格，对于 NAS 机箱来说，通常都是以 3.5 英寸来设计的，外置硬盘座或者硬盘笼也是一样，如果手里有 2.5 英寸的硬盘，需要注意是否可以兼容使用。

不过 2.5 英寸机械硬盘基本上都是 SMR 叠瓦盘，所以…… 我是冇得拣，只考虑 3.5 英寸的机械硬盘。

接口

目前硬盘接口主流使用的是 SATA 、 mSATA 和 M.2 接口，另外还有一些是 PCIe 接口（较少）。

M.2 接口目前主要运用给迷你固态硬盘（ NMVe SSD ）， mSATA 也是一种比较小的固态硬盘（我现在主机里就用了一个 mSATA 的 SSD 做系统盘），而 SATA 则是机械硬盘和普通的 2.5 英寸固态硬盘使用。

SATA 现在又分为 SATA 2 （又称 SATA 3G ）和 SATA 3 （又称 SATA 6G ），主要区别在传输率， SATA 3 的传输速率可以达到 6 Gb/s ，而 SATA 2 接口的传输速率则为 3Gb/s ，理论上 SATA 3 接口是 SATA 2 的两倍。

所以购买机械硬盘的时候优先考虑 SATA 3 。

但现在也有外置硬盘座，是可以使用 USB 3.0 来代替 SATA 口和主板连接，传输速度不会差太多，不过不适合所有人，最好确认自己家里是否会有外力因素去碰到它（例如你家的猫会不会上桌 - - ），或者是容易发生地震之类自然灾害的地区，硬盘座需要有很稳定的外界空间才可以考虑。

转速

机械硬盘常见的转速一般有 5400 转、 5900 转、 7200 转，硬盘的转速越高，读写的速度就越快，但是相对的，噪音也更大一些，一般来说 NAS 选用 5400 转也够用。

硬盘容量

这里就不说一共需要多少个 T 的问题了，只讨论是买几个盘。比如京东二手上面西数 500G 的二手盘才 39 块钱，而一样是西数的 2T 二手盘却要 ￥ 219 ，在有一个四盘位的机箱，并且需求是 2T 容量的情况下，是不是买 4 个 500G 的比买一个 2T 的划算？

当然不是，因为每增加一个硬盘，耗电量就会增加，所以尽量每个盘都是越大越好，虽然只看硬盘的耗电不算太大，但是 NAS 通常都是 7x24h 持续运行，加上其他的配件消耗每一个都多一点的话，在广州和深圳地区，除了住小区可以享受 6 毛钱一度的电费，其他地方都是 1.5 元一度电，这么贵的电费长时间算下来，可能真的很不划算。

参考资料

• SMR 瓦楞式堆叠磁盘是什么东西，和传统磁盘有啥区别
• 这些硬盘不要买！2023 那些不推荐的机械硬盘
• 垂直盘和叠瓦盘区别？叠瓦盘为什么不推荐？2023 年机械硬盘购买推荐
• 2023 年，HDD 机械硬盘推荐，尽量不选叠瓦盘
• 为什么说「买盘别买叠瓦盘」？一文带你看懂 SMR、CMR 的区别
• 一文看懂硬盘的主要接口和传输速度
• SATA、mSATA、M.2、M.2（NVMe）、PCIE 固态硬盘接口详解

搭配方案

在确定最终组装方案之前，自己考虑了三个方向的方案如下，其中价格暂时都是以淘宝和京东的价格作为参考，实际购买的时候可以去拼多多比价。

尺寸的单位都是 “毫米” ，顺序是 “长 x 宽 x 高” 或者 “长 x 宽” 。

补充说明一下：

这里的方案一二三都是调研阶段整理的，在这里就不改了，我自己实际的最终搭配见最前面的 最终组装方案 。

另外这里时 2023 到 2024 期间的推荐，再往后请自己搭配了，毕竟硬件会过时。

方案一：迷你 + 外置

• 搭配说明：自选迷你主机 + 硬盘笼 + 若干个 3.5 英寸的机械硬盘
• 主要优点：存储容量大（外挂机械硬盘），机箱迷你低功耗，搭配省事
• 一些缺点：拖个硬盘笼或者硬盘支架，怎么看怎么丑
• 适合对象：刚入门 NAS ，还懵懵懂懂，但有一定存储需求的玩家
• 千元入门：见下表

先列一下需要的配件和价格：

配件总价格：￥ 489 ，如果觉得配件的价格占比偏高，可以适当调整硬盘方案，例如改成 2 个 1T ，或者是小黄鱼或者京东二手买二手盘。

目前选的日立虽然早已被西数收购变成 HGST 系列，据说现在卖的价格亲民的都是拆机盘，但查了一下好像质量还可以，故障率非常低，这个预算也不奢求太多，我感觉可以买来试试。

如果选购热门牌子像西数、希捷等，一定要注意查好型号是 SMR 还是 CMR ，很多详情页都不会显式告知是不是 CMR ，那么大概率是 SMR 。

再看看主机的选择和方案总价：

关于畅网和倍控，据说畅网贵一些的原因是畅网的机箱散热和电源会好一些，差价也基本都差在机箱和电源上。

方案二：纯迷你主机

• 搭配说明：自选迷你主机 + 1 个迷你固态
• 主要优点：主打各种迷你，低功耗，搭配省事，颜值一般也高
• 一些缺点：存储容量一般（仅用一个固态硬盘）
• 适合对象：刚入门 NAS ，还懵懵懂懂，并且存储需求不大的玩家
• 千元入门：见下表

在方案一的基础上，把机械硬盘换成 NVMe 的固态硬盘即可，整体的价格方面会相对方案一低一些。

但这个方案因为走了 SSD 存储，所以可能需要关注一下本身硬盘速度是否有影响。

方案三：自组全部

• 搭配说明：自选主板 + 带硬盘笼的机箱 + 若干个 3.5 英寸的机械硬盘
• 主要优点：存储容量大（大容量机械硬盘便宜），机箱通常比较帅（也可以自己选择 3D 打印）
• 一些缺点：比较笨重（例如机箱重大 4.26kg ，加上其他的硬盘、风扇，可能高达 10 至 15 斤），成本也较高
• 适合对象：有玩硬件的经验，虽然刚入门 NAS ，但搭配起来不费劲的老司机
• 千元入门：见下表

暂无时间推荐，根据前面基础知识部分的内容去搜符合要求的配件。

写到这里好累，周末两天就过去了， 系统的安装现在推荐直接用飞牛 fnOS ，官方有很靠谱的说明，开箱即用基本没问题。除了系统安装之外，还有 Docker 、 Clash 代理 、基于 FRP 和 Cloudflare Tunnel 的两套内网穿透方案部署等等（飞牛现在很多都内置支持了），很多东西也可以玩一玩。

这是一本以 Vue.js 的 3.0 版本为核心技术栈，围绕 “前端工程化” 和 TypeScript 的知识点展开讲解的前端入门书籍，主要面向以下读者人群：

1. 掌握了基础的 HTML 页面编写知识，想学习一个主流前端框架的新手前端工程师
2. 已经学会了 Vue 2 ，面对 Vue 3 的大版本更新，想快速上手使用的前端工程师
3. 非职业前端开发，但涉及前端的工作，需要掌握一个主流前端框架的全栈工程师

书里面的知识点是按照工程师做项目的顺序梳理的，比较循序渐进的一个过程，读者可以收获到这些知识：

1. 了解如何入门前端工程化开发，掌握 Node.js 和 npm 的使用
2. 掌握前端领域多年来趋势走高、带有类型支持的 TypeScript 语言
3. 上手主流前端框架 Vue.js 的全新版本，并且在遇到常见问题时知道如何解决

看到这里，我估计有部分读者会觉得眼熟，有熟悉的感觉是对的！因为在它被正式出版之前，有另外一个名字是叫《Vue3 入门指南与实战案例》，最早是部署在我的博客网站上作为本书配套案例和代码资源的 开源版本 分享的。

截止至 2023-05-03 五一假期的最后一天，开源版本已经累计了大约 220 万的阅读人次，受到了不少读者朋友的关注和支持，所以我相信很多人是看过它的在线版本，上面这段话其实就是前言里面的一部分。

今天这篇文章更主要是想分享一下这本书的由来，还有一些关于我、关于写书这些事背后的一些故事，希望感兴趣的读者可以继续支持！

目录详情和购买地址

先放上纸质书的购买地址吧，关于书的目录和内容介绍可以在商品详情查看：

☞ 访问 京东商城 购买

☞ 访问 天猫商城 购买

如果您对我的作品认可，建议购买纸质版，纸质书在电子书的基础上，经过机械工业出版社的编辑老师们的内容优化、校对勘误、排版美化，更成体系，在此特别感谢李晓波编辑对我将开源作品出版为纸质作品的支持，李老师全程帮忙跟进了无数的大事小事，也给我科普了很多出版方面的知识，十分尽职！

这本书怎么样？

在出版纸质书之前，电子版就开通了基于 GitHub Issue 的评论功能，收到了很多读者给我的反馈和交流，摘选了一部分如下（排名不分时间先后）：

也有来自宝岛的小姐姐热心安利（我就说某段时间突然有很多来自台湾的工程师关注，然后 Google 了一下发现了这个推，感谢我的热心网友们！

因为之前有热心读者问我有没有赞赏渠道，所以我从去年 10 月份在文档上挂了一个赞赏码，可以给我家三只猫猫打赏点罐头，也收到了很多读者的捐赠，有好几笔是大额的赞赏，特别特别感谢！！！

所以关于这本书的内容质量，我相信您看到这里时应该也有了一个大概的了解！

放上我家三只猫，欢迎在线吸猫！

这本书是怎么写出来的？

作为写了一本大约 32 万字的成品书籍的作者，我一开始并没有很功利的想把它写成一本书，它最早最早的前身其实是我无数日夜在学习过程中的笔记碎片。

刚开始关注和使用 Vue 3 的时候还是 2020 年，那段时间资料很少，相关的官网也只是基于 Vue 2 的内容向上适配了一下，并且只有英文版，其他的随手可得的资料，真的好少好少…… 我那段时间也算处于一个比较早期的开荒阶段，遇到问题也只能 Google 和 StackOverflow ，还有在 GitHub 仓库的 Issue 区和源码挖挖看有没有解决方案。

再后来发现还是不太够用，慢慢地又跑去 RFC 仓库 挖掘一些还没有正式公开，但其实已经实现的 “隐藏功能” ，期间也整理过一些文章分享出来过（例如： Vue3.0 最新动态：script-setup 定稿 部分实验性 API 将弃用 ， Evan 大佬还在评论区亲自帮忙解答大家的问题）。

因为开荒的过程都是利用本就不多的休息时间，所以早期为了解决各种问题和先把项目做出来，也没有第一时间整理博客笔记，我通常的习惯都是先把找到的资料丢给我一个专门存档临时笔记的微信小号，作为一个可检索的 “便签” 。

再后来发现实在太多了，这么零散的记录我自己回头也容易忘记，秉着对费曼学习法的多次实践（用输出来倒逼输入，真的特别有效！），逐步整理出了第一个版本，在 2020 年国庆节那会部署到了博客上面，刚上线的时候它还只是一本很纯粹的关于 Vue 3 的入门学习指南，内容比较单一，阅读门槛也比较高（需要本身已经熟悉了 Vue 2 才能看懂我在说什么）。

很感谢第一波读者的鼓励，很热心地给了我评论反馈，还收到了很多邮件交流遇到的问题，经过不断地迭代，慢慢地补充了很多通俗易懂的例子，并且逐步增加了关于前端工程化和 TypeScript 的入门学习内容。

期间还有很多读者自发帮我宣传（ e.g. PR #6075 ），让我写的内容逐步被更多的人看到，所以到了后面一共有三家出版社联系了我出版事宜，也才有了后面这些出版相关的事情（因为收到不同出版社的邀请在时间上跨度比较大，所以我也是选择了最早联系我的李晓波编辑和机械工业出版社，在这里也很感谢其他出版社的编辑对我的作品的认可！）。

我是一个什么样的人？

再来说说我自己，我并不是一个很纯粹的程序员。

认识我久一点的朋友也知道我并不是从毕业就一直在做开发，虽然读书那会选了网络专业也勉强算是科班出身（哈哈哈哈我真的不太想提及这些往事，因为那个时候自己也还挺不懂事，老在挂科边缘徘徊，经常这边老师教完知识，过段时间我又还给老师了，反正就是成绩不怎么好的那一类人），相对于做开发或者运维等更重技术的岗位，我那个时候更喜欢打游戏、混各种论坛社区写一些挂机脚本、喜欢看人家怎么做产品设计等东西，所以毕业后跑去游戏行业做了产品运营（我在 UC 的那两年就是做产品运营）。

一开始倒是觉得做运营挺有趣的，但后来发现我的运营 KPI 很大程度依赖于在重要节点的各种活动和宣传合作页面用于推广，但 “拿不到排期” 这个事情总是在阻碍着我达成 KPI ，后来我就跟技术部的同事发起了一个小小的请求：“一些简单的需求页面我自己写，你们有空的时候能不能稍微帮我审查下代码和安排部署？” ，然后我就开始在工作时间干起了写代码的活，我负责的运营业务的数据指标也因为需求能如期上线而基本能按预期跑满，从此就一发不可收拾。

但那段时间我还不敢把自己定位为程序员去换工作，毕竟学的越多越觉得自己渺小，计算机的世界里有太多自己没有接触到的东西，所以 2015 年从 UC 跳槽去网易游戏的时候，我还是去面的运营岗位，进入了大话手游业务线，那段时间刚好面临大话手游即将上线，已经在计划中的需求 1234 是真的多，但又是喜闻乐见的 “没有排期了” ，所以入职后作为一个运营，安排给我的第一个任务是写一个答题器，我就……（此处是 Max 的问号脸.jpg ）

其实是我当时的运营简历也写了我会写页面，在网易的面试过程中也聊到了我在 UC 自己做自己的需求的经历，所以当时的网易总监也知道我可以写…… 经过 “一直需求顺利上线一直爽” 的阶段后，再后来就在部门内就成立了自己的技术组、产品组，开始有了自己的前端开发和产品策划等不同岗位，所以从 2016 年开始我就开始正式以写代码为生了，到 2023 年的今年，刚好 7 年。

兜兜转转从技术专业跑去做产品运营，再从运营又杀回来做技术，经常有人问我那几年后不后悔，也有人很好奇我转回技术这段过程难不难。

先说关于难不难，我只想说两个字：“热爱” ！当你对一件事情有了足够的热爱，真的没有什么难的。这里的 “热爱” 指的是可以长期保持数年的喜欢不变心，而不是三分钟热度的 “教练我要学” 盲目跟风。

再说说关于后不后悔这件事，至少目前的 7 年里是没有后悔的，我本身从小就不是一个按部就班的人，总是跟着我的兴趣去做我喜欢的事情，青少年时期我的同学都喜欢看球、喜欢听流行歌曲、喜欢唱情歌，而我那个时候就已经是一个享受着孤独沉迷在自己世界里的听摇滚乐的人，从来不看球，从来不听情歌，至于在其他人眼里可能显得比较独来独往和特立独行，从小好像就不是特别在意。

我家境很一般，在我工作之前，我爸爸妈妈每天忙碌养家也只是赚个温饱，所以我基本上是没有零用钱这种东西，虽然早在初中高中那会就想玩乐队，但吉他贝斯等乐器和学琴的费用在当时真的是完全消费不起，但也没有妨碍我对它们一直保持热爱，买不起我就自己做，自己画版型，自己锯木料，自己上油漆，给自己做了最喜欢的 BEYOND 乐队吉他手阿 Paul 在 1991 年演唱会上的那把斯坦伯格的无头吉他模型满足自己内心的 Rock'N Roll ，这可能是我最早期的自己的需求自己实现吧啊哈哈哈。

工作后身边的同龄人开始恋爱结婚生子学车考驾照，我是完全反着来，因为不喜欢坐车和极少出门，所以我到现在也没有想考驾照的念头，反而在爸妈眼里的 “你也老大不小了（后半句就是你该成家了…… ）” 的年纪才开始自学弹琴、组乐队玩演出圆我当初的乐手梦，当年第一把琴还是借的，只想着过把瘾，结果发现真的放不下了，到了后面自己也走上了买自己喜欢的琴的不归路。

再后来有了一些志同道合的伙伴一起夹 Band ，有幸也登上了几次三千多人的舞台，在别人都是唱流行歌曲和谐氛围里，我们又玩起了相对小众的新金属，哪怕现在我同学孩子都已经很大了，我还每天沉迷在 “塞狗、发克鹰、馊兽” 这样的嘶吼音乐里（这是 Slipknot 活结乐队在 Psychosocial 这首歌的某次现场版开场，特别燥的一个 Live 版）……

对于爱好和生活之间的平衡，这一点我特别佩服中山大学的何广平教授，白天衬衫教书，晚上甩头演出，双面人生太让我羡慕了！（可戳： 一边是量子物理，一边是极端金属，中大教授诠释科研与音乐的完美融合 了解何教授）。

头发也是从 2018 年初就再也没有去剪过，从光头到莫西干再到现在的长发及腰，我感觉我还可以继续留下去……

最让我走上 “只过自己喜欢的生活” 的不归路就是下定决心去文身了，从不到 20 岁的时候就想要纹一条花臂，也是念念不忘了多年后终于开始了行动，第一个文身是我的琴，然后是我的猫，然后是音乐元素，还有一些逆境阶段的有意义的图，有一些是自己设计点草图，到了后面默契上来了就全部交给我的专属文身师 Johnny 了，从 2016 年文身到现在，还在继续加图案，每一个图案都在自己的人生阶段里有着不同的意义。

说了这些往事，主要还是想回到前面说的，只要保持足够的 “热爱” ，很多困难真的不是困难，而且因为热爱，也会自然而然的遇到一群志同道合的好朋友，很感谢这么多年一路陪我玩陪我成长以及在我转行过程中给到了很多帮助的同事好友！

如果对我的更多往事感兴趣，可以扫码查看我之前整理的我在网易五年的工作和生活的记录。

表达能力如何培养？

最后分享一个可能会比较多程序员都比较关心的问题，如何锻炼自己的码字能力和表达能力。虽然我很宅，不爱社交，但很多读者在阅读了我的文字之后给我的反馈都是看完容易理解，性格和表达似乎出现了矛盾？其实不然。

我之前写过一篇文章叫 Markdown 工程师的一周 ，分享过我曾经一周写了大约 25 个小时的 Markdown 文档，几乎一天有 5 个小时在码字。

为什么我不觉得写文档是个很费劲的事情？因为我自己常常保持的习惯有主要两个：

一个是保持每天写日记的习惯，把自己的喜怒哀乐都记录到日记里，开心的时候记录起来以后可以回顾，不开心的时候用文字把负面情绪输出走，这个方式可以很好的让自己不会把坏情绪带回家里或者带入到工作中，从几个字到两三千字我都写过，内容的多和少并不需要很刻意的去要求，重要的是这一天对你来说，过的有没有意义，我从 2019 年把写日记的习惯重新培养起来到现在也有 4 年了，已经连续写了 4 年日记，没有中断过。

另外一个习惯是上面说的费曼学习法，把自己学到的东西输出成博客文章或者其他什么载体都可以（例如下面的两个 PPT ，是我之前在一些分享会上的演讲稿，已脱敏），一开始写分享内容时可能会觉得无从下手，但是如果能够长期保持习惯，久而久之自己所写的东西就会开始有了逻辑有了条理。

• 六步写出有效的需求文档 从技术的角度分析：产品需求如何 “以德服人”
• 前端技术复盘 面对停运项目重启复活时的思考与落地

因为上面两个习惯，让我后来开始记录我平时做菜时的菜谱也蛮多人爱看。

写在最后

能看到这里的朋友对我真的是真爱了，希望我的书也能给到您一些帮助，希望您在继续学习的路上，或者转行的路上，都可以实现自己想达到的目标！

再次附上买书链接：

☞ 访问 京东商城 购买

☞ 访问 天猫商城 购买

如果想问我接下来会做什么？我也是继续保持学习哈哈哈哈哈哈！我在今年三月份刚刚换了新工作，来到了一个很牛逼的团队，技术氛围特别好，队友们的能力也好强，未来也有很多我之前没有接触的东西，我也还在继续成长！

最后的最后，分享一下我保持学习的动力和精力的秘诀……

谢谢您的支持！

因此 B 项目想升级 A 项目的功能，并不是不可能，冲突也不一定会很多。不过因为不是每个版本都升级，所以如果手动合并代码，工作量又比较大。分享了几个方案给他尝试，当然这些操作对我来说也不怎么常用，所以记录起来，以后自己用到也不用重新踩坑。

下面的演示都基于同一个 Git 仓库的不同分支，实际处理中，可以选择把 B 项目放到 A 项目的某个分支来实现合并，也可以通过 git remote add <shortname> <url> ，将两个项目关联到同一个 Git 远程仓库。

合并某个版本

先看看一个版本合并的操作，假设 B 项目不想完全升级到 A 项目的最新版本（可能因为最新版本是一个包含破坏性升级的 Major 版本，出现了很多不兼容的情况），那么可以选择其中一个 Minor 次要版本进行升级。

处理思路

由于并不是每个项目都有打 Tag ，所以可以选择指定某个 Commit Hash 作为临界点。在这个例子里，将 A 项目在某个 commit 记录之前的功能，都需要同步给 B 项目，这里使用 git merge <commit_hash> 命令来实现。

具体操作

随便拉取了一个旧的版本，拉取深度为 10 （主要参数是 --depth 10 ，其他的 --branch 和 --single-branch 可以视情况指定，这里只是为了单纯拉取 main 分支的代码）。

git clone https://github.com/chengpeiquan/test.git --branch main --single-branch --depth 10

进入仓库文件夹，使用 git log 命令查看本地仓库和远程仓库的 main 分支差异（这里使用了 --oneline 参数简化了提交记录的展示）。

cd test
git log --oneline main origin/main

看一下 Log ，确实是 10 条 Commit 差异：

# git log --oneline main origin/main
3ad0947 (HEAD -> main, origin/main, origin/HEAD) chore: backup
fc322fe chore: backup
1cc6c01 chore: backup
4898c9c chore: backup
8258834 chore: backup
cb7d560 chore: backup
10b3bb5 chore: backup
2119218 chore: backup
1c0c5ba feat: backup
f49e8b0 (grafted) chore: backup

将本地的 Commit 记录重置到拉取时的那个 Commit ，如果不执行这一步，在 Merge 的时候会提示 Already up-to-date. 的信息，无法合并。

git reset --hard f49e8b0

在 10 条 Commit 差异里，现在使用 git merge <commit_hash> 命令合并第五条 Commit （它的 Hash 是 cb7d560 ），保留 5 条差异。

git merge cb7d560

合并成功反馈：

# git merge cb7d560
Updating f49e8b0..cb7d560
Fast-forward
README.md | 14 +++++++++++---
docs/introduction.md | 1 -
docs/zh/introduction.md | 1 -
3 files changed, 11 insertions(+), 5 deletions(-)
delete mode 100644 docs/introduction.md
delete mode 100644 docs/zh/introduction.md

再次查看本地 main 分支和远程 main 分支的差异：

git log --oneline main origin/main

本地的 HEAD 已经在第五条了：

# git log --oneline main origin/main
3ad0947 (origin/main, origin/HEAD) chore: backup
fc322fe chore: backup
1cc6c01 chore: backup
4898c9c chore: backup
8258834 chore: backup
cb7d560 (HEAD -> main) chore: backup
10b3bb5 chore: backup
2119218 chore: backup
1c0c5ba feat: backup
f49e8b0 (grafted) chore: backup

为了避免覆盖，创建一个新分支来提交刚刚本地合并后的代码：

git checkout -b dev

再次检查一下新分支 dev 分支和远程 main 分支的差异：

git log --oneline dev origin/main

确认没有问题（因为是从本地 main 分支创建的，所以代码是一样的，但在进行敏感操作之前，还是养成一个二次检查的习惯）。

# git log --oneline dev origin/main
3ad0947 (origin/main, origin/HEAD) chore: backup
fc322fe chore: backup
1cc6c01 chore: backup
4898c9c chore: backup
8258834 chore: backup
cb7d560 (HEAD -> dev, main) chore: backup
10b3bb5 chore: backup
2119218 chore: backup
1c0c5ba feat: backup
f49e8b0 (grafted) chore: backup

可以提交到远程的 dev 分支了（也就是实际上 B 项目代码所在的分支）。

git push -u origin dev

合并某个提交

有时候仅仅想单独合并某一条或者某几条 Commit 的改动，不希望包含该 Commit 之前的其他 Commit ，可以选择这个方案来处理。

处理思路

与 合并某个版本 的操作不同，这种情况会产生新的 Commit Hash ，因此整个提交历史会被打乱，所以比较适合简单的代码合并，例如某个模块新增了功能，而其他的功能并不需要，只想要这个模板的新功能，那么选择这个方案会比较合适。

这个方案就不再是使用 git merge 了，而是使用 git cherry-pick <commit_hash> 命令来实现。

具体操作

继续在 dev 分支上操作，也是先查看差异：

git log --oneline dev origin/main

由于前面 合并某个版本 的操作是合并第五个 Commit 以及之前的提交记录，因此还有 5 个未同步的记录。

# git log --oneline dev origin/main
3ad0947 (origin/main, origin/HEAD) chore: backup
fc322fe chore: backup
1cc6c01 chore: backup
4898c9c chore: backup
8258834 chore: backup
cb7d560 (HEAD -> dev, main) chore: backup
10b3bb5 chore: backup
2119218 chore: backup
1c0c5ba feat: backup
f49e8b0 (grafted) chore: backup

这里挑选未同步的记录里面的一个，只合并这个：

git cherry-pick 4898c9c

合并成功反馈：

# git cherry-pick 4898c9c
Auto-merging README.md
[dev 3f8b616] chore: backup
Date: Mon Dec 5 13:54:43 2022 +0800
1 file changed, 5 insertions(+), 1 deletion(-)

现在重新查看本地 dev 分支和远程 main 分支的差异，可以看到多出来一个新的提交了。

# git log --oneline dev origin/main
3f8b616 (HEAD -> dev) chore: backup
3ad0947 (origin/main, origin/HEAD) chore: backup
fc322fe chore: backup
1cc6c01 chore: backup
4898c9c chore: backup
8258834 chore: backup
cb7d560 (main) chore: backup
10b3bb5 chore: backup
2119218 chore: backup
1c0c5ba feat: backup
f49e8b0 (grafted) chore: backup

其他补充

在演示项目上操作通常还是很顺利的，但实际项目里可能会存在代码冲突，建议在操作时，按照小版本的提交去合并同步，减少冲突的解决成本。

工作与生活

2020 年疫情爆发那年发生了很多事情，最终也决定从服务了五年的网易公司离职（见 记录一下在网易五年来的工作与生活），随即和几个朋友跟着大佬去了深圳，因为大家都是扎根广州，所以都把深圳当成一个临时过渡的城市，所以今年时机成熟的时候就又一起回到了广州。

回广州后也终于不用再苟在城中村里了，在依山傍水的山景房里，三只猫也迎来了久违的阳光，每天睡到自然醒，醒了有东西吃有玩具玩，还不用出门工作，过的比我还幸福。

我从五月底回来后就一直很忙，因为广州这边也是刚成立的新公司，太多事情要忙，加上业余时间也有其他事情， 菜谱 也慢慢停更了，不过偶尔还是有在做饭，新的一年看看调整下生活节奏重新运营起来。

虽然工作很忙碌，但在初创公司的日子里倒也是很有趣，因为人少（目前加上老板还不到十五个人），所以自己也有机会开始承担起一些前端工程师之外的开发工作，例如写 App ，写客户端，写服务端，写爬虫，写区块链，当然都是围绕着 Node.js 进行的全栈开发。

写着写着就没有什么时间写页面了，所以今年也是把 Tailwind CSS 这一类原子框架大幅度的往工作项目里用，这样在需要写页面的时候可以不怎么写样式了，对 Flex 布局熟悉的前端工程师来说， Tailwind 风格的开发模式做东西真的非常快，很适合初创公司老板说 “啊啊啊这个东西很着急” 然后第二天就可以给到他。

这一年是真的忙碌（见下文的 开源社区 部分），以至于几乎没有什么运动量，可能也因为运动太少，所以从九月份开始，从痛风发作到新冠病毒，陆陆续续当了一个季度的病号，不过有一点算是不幸中的万幸，就是因为一直宅着，所以年底新冠阳性的时候仅仅只是个弱阳，低烧了一个晚上就开始在恢复健康了，相对于在朋友圈看到一些朋友病得五颜六色，我还是挺幸运的。

另外关于生活的话，就是头发达到了历史上的最新长度，往后甩的时候已经过了腰了，虽然发质一如既往的差，但我并不关心发质哈哈哈哈，长度才是王道。

开源社区

今年在 GitHub 的活跃度比去年高了不少，而且很神奇的达到了全勤，因为疫情的原因，还有换城市和新工作等事情，今年也没有出远门或者回家待几天，每天都在有电脑的屋子里待着，所以每天都有在 GitHub 上操作（截图生成自 GitHub Contributions ），也归功于今年把很多有的没的代码都托管到 GitHub 上了，包括一些 to-do list 也会有个 Markdown 仓库作为临时笔记，很方便哈哈哈。

虽然这么活跃，但开源项目其实没有参与多少，基本上都在维护去年的一些旧项目，其中投入最多的是之前写的那本关于 Vue 3 的书 Learning Vue3 。

今年一月份的时候在知乎收到一条私信，是出版社的编辑发现了我写的东西，邀请我参与到书籍的出版工作中。当时由于临近过年比较忙，没有立即答复是否参加，后面四月份编辑老师又联系了我，在考虑了自己的时间和目前手里头比较有积累有篇幅的内容后，咨询了是否可以用现有的开源内容整理出版（还举了阮一峰老师的 ES6 入门教程 的例子），得到了肯定的答复之后，就开始安排时间调整 Learning Vue3 的内容。

由于当时 Vue 3 已经成为 npm 安装时的默认版本，并且中文官网也建设起来了，考虑到继续单独讲述 Vue 3 的内容显得有点 “过时” （毕竟当时写这本书的背景是国内没有什么 Vue 3 的资料，并且还处于公测但未完全替代 Vue 2 的阶段），在出版社编辑老师的建议下，续写了关于前端工程化的内容，以降低本书的学习门槛，所以可以看到我从 四月底的更新记录 就慢慢不再局限于 Vue 了，而是一直在更新前端工程化的内容。

再之后的几个月就一直在补充新内容，并且按照出版社的供稿规范调整了叙述风格，最终整个文档的风格就变得比较有 “专业性” ，不再是嘻嘻哈哈的逗逼语气，自己感觉有点像阮一峰老师，确实在阮老师的博客里受到了很大影响。

很高兴续写的内容得到了线上读者的认可，不仅仓库从 100 Star 慢慢涨到了现在接近 500 Star ，还有很多读者给我留言，给了我很大的鼓励！

调整后的叙述风格也被读者认可，在 2022 年底突然有一群台湾开发者关注了我的 GitHub 账号，搜索了一下才发现原来 被台湾一位技术大 V 推荐了 ，她很喜欢我的风格，我很开心哈哈哈，付出得到了回报，得到了认可！

其他的开源项目大部分是一些 npm 包，总下载量也突破 35 万次了（数据来源 npm-stat ）。

有个 Vite 插件被大佬的项目引入后带火了，现在每周大约保持在 7k 左右的下载量，也收到了其他开发者的 PR 贡献（ #16 ），期间认真的评审了代码和给予了意见点评，直到那天才感觉在认真参与开源项目协作，在此之前都是自己单打独斗，或者发起一些没有什么修改意见的翻译 PR ，很少这样在 PR 过程中讨论功能的取舍。

还有一个使用量比较多的插件是一年多前做的一个自用的小工具，很久没维护，结果一直有人用，前段时间还提了一些反馈，所以年底有空于是重新维护了起来，还用 Photoshop 鼠绘了个 Logo ，偶尔设计点东西还挺有意思的，虽然渣渣，但我觉得很贴合用途哈哈哈。

另外还有一点比较值得高兴的是，新开坑的开源仓库都已经全部使用英语了，包括代码里的注释，还有 issue 的交流，虽然语法和用词什么的不一定对，但在 Google 翻译校验了一下还是可以识别的，多读多写多练习，总有一天可以不太依赖翻译工具的。

新年展望

刚好很多事情都在 2022 年底弄完了，新的一年业余时间应该不会那么忙了，我要多运动，多爬山，明明现在住的地方对面就是一座山，我居然一次都没有爬过，真是浪费啊浪费可耻哈哈哈。

然后把三年没弹的贝斯重新弹起来，太久没有弹琴了，自从去了深圳，总感觉人在漂泊，以至于从 2020 年之后就没有再弹过琴，希望今年可以重新积累一些可以演奏的曲子。

技术方面，长远的规划不好说，梳理了一下最近几个月的计划吧：

1. 重构博客（上一次是 2020 年 1 月，也有两年了），技术选型还是偏向于比较新的前端技术栈，找个时间调研一下
2. 认真学一下 React ，其实很久前就有想法，但因为缺乏可落地的个人项目，所以一直没动手，只是简单的写了几个 demo ，去年写 App 的时候因为主要技术栈还是 Vue ，所以选了 uni-app ，但感觉体验并不是太好，把 React 玩熟悉之后以后也可以切入 React Native 开发
3. 重构之前写的命令行工具 create-preset ，一个模板拉取工具，现在在用的 GitHub 镜像挂掉了一直没去修，打算把一些自己维护的模板处理成本地一起发包，不走 GitHub 下载了，其他人的社区模板就继续拉仓库，不过要考虑现有的 API 兼容，只能是无感知的重构，感觉要做的事情也不少

其他的可能就是 Web 3 方面的开发继续深入吧，智能合约和 dApp ，也是未来的趋势，并且基本上都是以前端的技术栈为主，作为前端工程师，天生有前端优势的情况下，不玩下区块链多可惜！

参考收藏夹：凶杀案·刑侦与法医

使用方法

这是一个 Node.js 项目，因此需要提前安装 Node.js 。

# 克隆仓库到本地
git clone https://github.com/chengpeiquan/zhihu-collection-helper.git

# 进入项目目录
cd zhihu-collection-helper

# 安装依赖（可使用 npm / yarn 等其他包管理器）
pnpm i

# 运行开始命令
pnpm start

不过程序正确运行的前提是需要先准备好一个 配置文件 。

配置文件

基于 dotenv 管理配置文件，创建一个名为 .env 的文件保存到根目录（与 src 目录同级别）。

注意所有的配置项的值都是字符串，也就是使用双引号括住。

其他说明

因为操作太快会导致行为限制（返回 403 Forbidden ），所以每次请求之前都通过 sleep 方法进行一次随机秒数的睡眠，可在这里调整操作间隔。

如果账号被限制了，等几个小时后再试就可以了。

预渲染和静态生成器比较接近，也可以参考我的 SSG 博客 用 vite-ssg 和 vite-plugin-pages 来处理。

不过 Vite 本身对预渲染也提供了原生的支持，简单的预渲染可以自己写写代码来改造实现。

HTML 部分

项目根目录下 index.html 里需要追加至少两条资源注入位置的注释：

并把入口文件改成 entry-client.ts ，原来的 main.ts 会作为客户端和服务端启动时的引用。

完整代码如下（源码：index.html ）：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!--title-->
    <!--description-->
    <!--keywords-->
    <!--preload-links-->
  </head>
  <body>
    <div id="app"><!--app-html--></div>
    <script type="module" src="/src/entry-client.ts"></script>
  </body>
</html>

其中除了两条必须的注释语句外，可选的部分见 SEO 优化 。

入口文件

普通项目是使用 src/main.ts 作为入口文件，需要改造成两个入口：

而原来的 main.ts 只作为入口函数导出，详见源码： main.ts

路由

不再需要手动配置路由结构了，改造后直接读取 src/views 的路由组件来生成页面路由。

详见源码： router

SEO 优化

做预渲染为的就是做 SEO ，所以需要自己提前配置好 SEO 的 TKD 三大要素，这里我也是放在 src/router 目录下一起管理了。

实现逻辑见 预渲染 部分的说明，这里是以最终每个页面的相对路径来判断要写入的 TKD 信息的。

export default [
  {
    url: '/',
    title: '首页',
    description: '这是首页',
    keywords: ['关键词1', '关键词2'],
  },
  // ...
]

详见源码： seo

预渲染

scripts/prerender.ts 这个文件是执行预渲染行为，可以按照路由目录的结构渲染为静态 HTML 文件。

运行 npm run generate ，可以把 dist/static 作为静态站点部署。

当然我也封装了 npm run build 一次性编译所有平台（ Client / Server / Static ）。

详见： package.json 里的 scripts 部分。

常见问题

改造过程中遇到的几个问题：

水合节点不匹配

控制台报错：

Hydration node mismatch:
- Client vnode: div
- Server rendered DOM: <!--app-html-->

警告来自于 hydration.ts ，一般可以无视……

当然也可以了解更多的知识点： understand-and-solve-hydration-errors-in-vue-js

路由跳转

控制台报错：

Unhandled error during execution of scheduler flush

需要使用 <Suspense /> 标签来包裹路由视图，详见 Suspense 。

<template>
-  <!-- <router-view :key="key" /> -->
+  <router-view :key="key" v-slot="{ Component }">
+    <Suspense>
+      <div>
+        <component :is="Component" />
+      </div>
+    </Suspense>
+  </router-view>
</template>

教程地址

点击访问：全局状态的管理 查看完整内容。

为什么写这篇内容

截止至 2022 年 4 月， Pinia 还没有被广泛的默认集成在各种脚手架里，官网也只有英文版，整理了教程便于提前学习。

由于 Vuex 4.x 版本只是个过渡版，Vuex 4 对 TypeScript 和 Composition API 都不是很友好，虽然官方团队在 GitHub 已有讨论 Vuex 5 的开发提案，但从 2022-02-07 在 Vue 3 被设置为默认版本开始， Pinia 已正式被官方推荐作为全局状态管理的工具。

Pinia 支持 Vue 3 和 Vue 2 ，对 TypeScript 也有很完好的支持，延续了 Vue3 入门指南与实战案例 的宗旨，在这里只介绍基于 Vue 3 和 TypeScript 的用法。

欢迎 Star

教程属于 Vue3 入门指南与实战案例 的一部分，如果觉得对你有帮助，欢迎到仓库给个 Star 鼓励。