TJC工作站

Firefly 博客示例功能合集

Mon, 29 Jun 2026 00:00:00 GMT

这篇文章把博客模板原有的示例文章合并到同一篇内容中，方便集中查看 Firefly 支持的写作、排版和扩展能力。原来的分散示例文章已隐藏，不再单独出现在文章列表中。

Firefly 一款清新美观的 Astro 博客主题模板#

来源：src/content/posts/firefly.md。Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

🌟 项目概述#

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

🖥️在线预览： Firefly - Demo site

🏠我的博客： https://blog.cuteleaf.cn

📝Firefly使用文档： https://docs-firefly.cuteleaf.cn

⭐Firefly开源地址：https://github.com/CuteLeaf/Firefly

⭐Fuwari开源地址：https://github.com/saicaca/fuwari

CuteLeaf

Firefly

Waiting for api.github.com...

Waiting for api.github.com...

00K

Waiting...

Firefly

🚀 技术架构#

静态站点生成: 基于 Astro ，提供极快的加载速度和优秀的 SEO 优化
TypeScript 支持: 完整的类型安全，提升开发体验和代码质量
响应式设计: 使用 Tailwind CSS 构建，完美适配桌面端和移动端
组件化开发: 支持 Astro、Svelte 组件，灵活可扩展

📖 配置说明#

📚 详细配置文档: 查看 Firefly使用文档获取完整的配置指南

Firefly 简单使用指南#

来源：src/content/posts/guide/index.md。如何使用 Firefly 博客模板。

这个博客模板是基于 Astro 构建的。对于本指南中未提及的内容，您可以在 Astro 文档中找到答案。

文章的 Front-matter#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
description: 这是我新 Astro 博客的第一篇文章。
5
image: ./cover.jpg
6
tags: [前端, 开发]
7
category: 前端开发
8
draft: false
9
---

属性	描述
`title`	文章标题。
`published`	文章发布日期。
`updated`	文章更新日期。如果未设置，将默认使用发布日期。
`pinned`	是否将此文章置顶在文章列表顶部。
`description`	文章的简短描述。显示在首页上。
`image`	文章封面图片路径。 1. 以 `http://` 或 `https://` 开头：使用网络图片 2. 以 `/` 开头：`public` 目录中的图片 3. 不带任何前缀：相对于 markdown 文件的路径
`tags`	文章标签。
`category`	文章分类。
`lang`	文章语言代码（如 `zh-CN`）。仅当文章语言与站点默认语言不同时设置。
`licenseName`	文章内容的许可证名称。
`licenseUrl`	文章内容的许可证链接。
`author`	文章作者。
`sourceLink`	文章内容的来源链接或参考。
`draft`	如果这篇文章仍是草稿，则不会显示。
`comment`	是否启用此文章的评论功能。默认为 `true`。
`slug`	自定义文章 URL 路径。如果不设置，将使用文件名作为 URL。
`password`	文章密码。设置后文章内容将被 AES-256-GCM 加密，访客需输入密码才能查看。
`passwordHint`	密码提示。显示在密码输入框上方，帮助访客回忆密码，也可以不加。

文章文件的放置位置#

您的文章文件应放置在 src/content/posts/ 目录中。您也可以创建子目录来更好地组织您的文章和资源。

1
src/content/posts/
2
├── post-1.md
3
└── post-2/
4
    ├── cover.png
5
    └── index.md

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 是文章 URL 路径的自定义部分。如果不设置 slug，系统将使用文件名作为 URL。

Slug 使用示例#

示例 1：使用文件名作为 URL#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/my-first-blog-post

示例 2：自定义 Slug#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
slug: hello-world
5
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/hello-world

示例 3：其他语言文件名使用Slug#

1
---
2
title: 如何使用 Firefly 博客主题
3
published: 2023-09-09
4
slug: how-to-use-firefly-blog-theme
5
---

文件：src/content/posts/如何使用Firefly博客主题.md

URL：/posts/how-to-use-firefly-blog-theme

Slug 使用建议#

使用英文和连字符：my-awesome-post 而不是 my awesome post
保持简洁：避免过长的 slug
具有描述性：让 URL 能够反映文章内容
避免特殊字符：只使用字母、数字和连字符
保持一致性：在整个博客中使用相似的命名模式

注意事项#

Slug 一旦设置并发布，建议不要随意更改，以免影响 SEO 和已存在的链接
如果多个文章使用相同的 slug，后面的文章会覆盖前面的
Slug 会自动转换为小写

Firefly 布局系统详解#

来源：src/content/posts/firefly-layout-system.md。深入了解 Firefly 的布局系统，包括侧边栏布局（左侧/双侧）和文章列表布局（列表/网格），以及自适应网格列数。

📖 概述#

Firefly 提供了灵活的布局系统，允许您根据内容需求和个人喜好自定义博客的视觉呈现方式。布局系统主要包括侧边栏布局和文章列表布局两个维度，它们相互配合，共同决定了页面的整体结构。

本文将详细介绍 Firefly 的各种布局模式、它们的特点、使用场景，以及不同布局组合的效果。

左侧边栏+列表布局

右侧边栏+网格布局

左侧边栏+三列网格布局

双侧边栏+列表布局

双侧边栏+网格布局

双侧边栏+网格瀑布流布局

一、侧边栏布局系统#

侧边栏是博客页面的重要组成部分，用于展示导航、分类、标签、统计信息等辅助内容。Firefly 支持两种侧边栏布局模式。

1.1 单侧边栏模式#

左侧边栏 (position: “left”)#

左侧边栏布局

右侧边栏 (position: “right”)#

右侧边栏布局

特点#

侧边栏固定在页面其中一侧
文章阅读区域体验更佳，更宽敞
更加简约，没有那么紧凑

适用场景#

传统博客风格
强调导航和分类的博客
需要突出用户资料的个人博客
内容为主，辅助信息次之的场景

Tip

可以通过showBothSidebarsOnPostPage配置是否在文章详情页显示双侧边栏

当position为left或right时开启此项后，文章详情页将显示双侧边栏，主页等其他页面保持单侧边栏

适用在只想用单侧栏，但在文章详情页想用对侧栏的目录等组件的场景

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "left", // 左侧边栏
4
  showBothSidebarsOnPostPage: true, // 是否在文章详情页显示双侧边栏
5
};

1.2 双侧边栏模式 (position: “both”)#

特点#

左右两侧同时存在侧边栏
主内容区域位于中间
最大化利用屏幕空间
可以展示更多辅助信息
适合宽屏显示器

布局结构#

双侧边栏+列表布局

双侧边栏+网格布局

适用场景#

宽屏桌面端浏览
信息密集型博客
需要展示大量辅助内容
专业性强的技术博客

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "both", // 双侧边栏

二、文章列表布局系统#

文章列表是博客首页和归档页的核心内容，Firefly 提供两种展示方式，并支持多种网格配置。

2.1 列表模式 (defaultMode: “list”)#

特点#

单列纵向排列
显示文章封面图
展示更多文章摘要
适合深度阅读

列表布局结构#

列表模式布局

优点#

✅ 视觉冲击力强，封面图吸引眼球
✅ 可以展示更多文章信息（摘要、标签等）
✅ 适合图片内容丰富的博客
✅ 移动端友好，单列更易阅读
✅ 兼容所有侧边栏配置（单侧、双侧）

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "list", // 列表模式
4
    allowSwitch: true,   // 允许用户切换
5
  },
6
};

2.2 网格模式 (defaultMode: “grid”)#

特点#

自适应列数，根据浏览器宽度自动调整
紧凑布局，信息密度高
适合快速浏览

自适应网格#

网格模式通过 columnWidth 配置卡片的最小宽度（单位 px），浏览器会根据容器可用宽度自动计算能容纳多少列。

网格布局

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "grid",
4
    allowSwitch: true,
5
    grid: {
6
      masonry: true,      // 开启瀑布流
7
      columnWidth: 320,   // 卡片最小宽度(px)，浏览器自动计算列数
8
    },
9
  },
10
};

2.3 瀑布流布局 (Masonry)#

Firefly 的网格模式内置了智能瀑布流布局支持，解决了网格布局中因图文混合文章导致的卡片高度不一致导致的空白问题。

瀑布流布局

智能排版：自动将卡片放置到最短的列，最大化利用垂直空间。
消除空白：通过绝对定位精确计算每个卡片的位置，让卡片紧贴上方卡片，消除垂直方向的空白间隙。
自适应列数：瀑布流同样根据 columnWidth 和容器宽度动态计算列数，无需固定配置。
配置灵活：您可以在 siteConfig.ts 中通过 postListLayout.grid.masonry 选项自由开启或关闭此功能。

三、布局组合指南#

Firefly 允许您自由组合侧边栏和文章列表布局。以下是各种组合的效果说明。

侧边栏模式	文章列表模式	推荐度	适用场景
单侧边栏	列表模式	⭐⭐⭐⭐⭐	摄影、设计、生活类博客，强调图片和沉浸感
单侧边栏	网格模式	⭐⭐⭐⭐⭐	技术、笔记类博客，平衡阅读与检索效率
双侧边栏	列表模式	⭐⭐⭐⭐⭐	需要展示大量侧边栏信息的站点
双侧边栏	网格模式	⭐⭐⭐⭐⭐	极客风格，追求最高信息密度

四、响应式布局行为#

Firefly 的布局系统具有智能的响应式设计，会根据屏幕尺寸自动调整。

为了保证最佳阅读体验，系统会在屏幕变窄时自动调整布局：

网格列数自动减少：网格模式的列数由 columnWidth 和容器宽度自动决定，屏幕越窄列数越少。
列表模式 -> 网格模式：当屏幕宽度小于 380px（超小屏设备）时，列表模式会自动切换为网格模式，以保证卡片内容的可读性。
双侧边栏 -> 单侧边栏：当屏幕宽度小于 1280px 时，会根据tabletSidebar配置显示单侧边栏，隐藏其中一个侧边栏，文章目录导航会切换成浮动目录导航。

五、常见问题#

Q1: 如何调整网格列数？#

A: 通过 columnWidth 配置卡片最小宽度即可。值越小，同等宽度下列数越多；值越大，列数越少。浏览器会自动根据可用宽度计算最佳列数。

六、总结#

Firefly 的布局系统给予了您更大的自由度，您都可以通过简单的配置实现。

我们建议您根据自己的内容类型和目标读者的设备偏好，尝试不同的组合，找到最适合您的博客形态。

Markdown 教程#

来源：src/content/posts/markdown-tutorial.md。一个简明的 Markdown 博客示例。

这是一个展示如何编写 Markdown 文件的示例。本文档汇总了核心语法与常见扩展（GFM）。

块级元素
- 段落与换行
- 标题
- 引用
- 列表
- 代码块
- 分割线
- 表格
内联元素
- 链接
- 强调
- 行内代码
- 图片
- 删除线
杂项
- 自动链接
- 反斜杠转义
内联 HTML

块级元素#

段落与换行#

段落#

HTML 标签：<p>

使用一个或多个空行分隔段落。（仅包含空格或制表符的行也视为空行。）

代码：

1
This will be
2
inline.
3

4
This is second paragraph.

预览：

This will be inline.

This is second paragraph.

换行#

HTML 标签：<br />

在行末添加两个或更多空格来产生换行。

代码：

1
This will be not
2
inline.

预览：

This will be not
inline.

标题#

Markdown 支持两种标题样式：Setext 与 atx。

Setext#

HTML 标签：<h1>，<h2>

使用等号 (=) 表示 <h1>、使用短横线 (-) 表示 <h2>，数量不限，作为“下划线”。

代码：

1
This is an H1
2
=============
3
This is an H2
4
-------------

预览：

This is an H1#

This is an H2#

atx#

HTML 标签：<h1>，<h2>，<h3>，<h4>，<h5>，<h6>

在行首使用 1-6 个井号 (#)，对应 <h1> 至 <h6>。

代码：

1
# This is an H1
2
## This is an H2
3
###### This is an H6

预览：

This is an H1#

This is an H2#

This is an H6#

可选：你可以在行尾“闭合” atx 标题。末尾的井号数量不必与开头一致。

代码：

1
# This is an H1 #
2
## This is an H2 ##
3
### This is an H3 ######

预览：

This is an H1#

This is an H2#

This is an H3#

引用#

HTML 标签：<blockquote>

Markdown 使用邮件风格的 > 作为引用符号。若手动换行并在每行前加 >，显示效果最佳。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4
>
5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
> id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown 允许“偷懒”：在一个硬换行段落中，只在第一行前加 > 即可。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4

5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

引用可以嵌套（引用中的引用），通过增加 > 层级实现。

代码：

1
> This is the first level of quoting.
2
>
3
> > This is nested blockquote.
4
>
5
> Back to the first level.

预览：

This is the first level of quoting.
This is nested blockquote.
Back to the first level.

引用内可包含其他 Markdown 元素，包括标题、列表与代码块。

代码：

1
> ## This is a header.
2
>
3
> 1.   This is the first list item.
4
> 2.   This is the second list item.
5
>
6
> Here's some example code:
7
>
8
>     return shell_exec("echo $input | $markdown_script");

预览：

This is a header.#

This is the first list item.

This is the second list item.

Here’s some example code:
1
return shell_exec("echo $input | $markdown_script");

列表#

Markdown 支持有序（数字）与无序（圆点）列表。

无序列表#

HTML 标签：<ul>

无序列表可使用 星号 (*)、加号 (+) 或 短横线 (-)。

代码：

1
*   Red
2
*   Green
3
*   Blue

预览：

Red
Green
Blue

等价于：

代码：

1
+   Red
2
+   Green
3
+   Blue

或者：

代码：

1
-   Red
2
-   Green
3
-   Blue

有序列表#

HTML 标签：<ol>

有序列表使用数字加英文句点：

代码：

1
1.  Bird
2
2.  McHale
3
3.  Parish

预览：

Bird
McHale
Parish

注意：像下面这样可能会“意外触发”有序列表：

代码：

1
1986. What a great season.

预览：

What a great season.

你可以用反斜杠转义 (\) 句点：

代码：

1
1986\. What a great season.

预览：

1986. What a great season.

列表中的缩进内容#

列表项里的引用#

在列表项内放置引用，需要将 > 符号整体缩进：

代码：

1
*   A list item with a blockquote:
2

3
    > This is a blockquote
4
    > inside a list item.

预览：

A list item with a blockquote:

This is a blockquote inside a list item.

列表项里的代码块#

在列表项内放置代码块，需要缩进两层——8 个空格或两个 Tab：

代码：

1
*   A list item with a code block:
2

3
        <code goes here>

预览：

A list item with a code block:
```
1
<code goes here>
```

嵌套列表#

代码：

1
* A
2
  * A1
3
  * A2
4
* B
5
* C

预览：

A
- A1
- A2
B
C

代码块#

HTML 标签：<pre>

将代码块中的每行缩进至少4 个空格或1 个制表符。

代码：

1
This is a normal paragraph:
2

3
    This is a code block.

预览：

This is a normal paragraph:

1
This is a code block.

代码块会一直持续，直到遇到未缩进的行（或文末）。

在代码块内，与号 (&) 和尖括号 (< >) 会自动转为 HTML 实体。

代码：

1
    <div class="footer">
2
        &copy; 2004 Foo Corporation
3
    </div>

预览：

1
<div class="footer">
2
    &copy; 2004 Foo Corporation
3
</div>

下文的“围栏代码块”和“语法高亮”属于扩展语法，你也可以用它们来书写代码块。

围栏代码块#

使用成对的反引号围起来（如下所示），就不需要四空格缩进了。

代码：

1
Here's an example:
2

3
```
4
function test() {
5
  console.log("notice the blank line before this function?");
6
}
7
```

预览：

Here’s an example:

1
function test() {
2
  console.log("notice the blank line before this function?");
3
}

语法高亮#

在围栏代码块后添加可选的语言标识，即可启用语法高亮（参见支持语言列表）。

代码：

1
```ruby
2
require 'redcarpet'
3
markdown = Redcarpet.new("Hello World!")
4
puts markdown.to_html
5
```

预览：

1
require 'redcarpet'
2
markdown = Redcarpet.new("Hello World!")
3
puts markdown.to_html

分割线（水平线）#

HTML 标签：<hr /> 一行中放置三个或以上的短横线 (-)、星号 (*) 或下划线 (_)。符号之间允许有空格。

代码：

1
* * *
2
***
3
*****
4
- - -
5
---------------------------------------
6
___

预览：

表格#

HTML 标签：<table>

这是扩展语法。

用竖线 (|) 分隔列，用短横线 (-) 分隔表头，使用冒号 (:) 指定对齐方式。

两侧的竖线 (|) 与对齐可选。用于表头分隔时，每列至少需要 3 个短横线。

代码：

1
| Left | Center | Right |
2
|:-----|:------:|------:|
3
|aaa   |bbb     |ccc    |
4
|ddd   |eee     |fff    |
5

6
 A | B
7
---|---
8
123|456
9

10

11
A |B
12
--|--
13
12|45

预览：

Left	Center	Right
aaa	bbb	ccc
ddd	eee	fff

A	B
123	456

A	B
12	45

内联元素#

链接#

HTML 标签：<a>

Markdown 支持两种链接样式：行内链接与引用式链接。

行内链接#

行内链接格式：[文本](URL "标题")

标题可选。

代码：

1
This is [an example](http://example.com/ "Title") inline link.
2

3
[This link](http://example.net/) has no title attribute.

预览：

This is an example inline link.

This link has no title attribute.

如果引用同一站点的本地资源，可以使用相对路径：

代码：

1
See my [About](/about/) page for details.

预览：

See my About page for details.

引用式链接#

可以预定义链接引用。定义格式：[id]: URL "标题"

标题同样可选。引用时使用：[文本][id]

代码：

1
[id]: http://example.com/  "Optional Title Here"
2
This is [an example][id] reference-style link.

预览：

This is an example reference-style link.

说明：

方括号中包含链接标识（不区分大小写，可在左侧缩进最多三格空格）；
随后是冒号；
再跟一个或多个空格（或 tab）；
然后是链接 URL；
URL 可选地用尖括号包裹；
可选地跟随标题属性，用引号或圆括号包裹。

以下三种定义等价：

代码：

1
[foo]: http://example.com/  "Optional Title Here"
2
[foo]: http://example.com/  'Optional Title Here'
3
[foo]: http://example.com/  (Optional Title Here)
4
[foo]: <http://example.com/>  "Optional Title Here"

如果使用空的方括号，则链接文本本身会作为名称。

代码：

1
[Google]: http://google.com/
2
[Google][]

预览：

Google

强调#

HTML 标签：<em>，<strong>

Markdown 使用 星号 (*) 或 下划线 (_) 表示强调。一个分隔符对应 <em>；两个分隔符对应 <strong>。

代码：

1
*single asterisks*
2

3
_single underscores_
4

5
**double asterisks**
6

7
__double underscores__

预览：

single asterisks

single underscores

double asterisks

double underscores

但如果两侧有空格，则会被视作普通字符而非强调语法。

你可以使用反斜杠进行转义：

代码：

1
\*this text is surrounded by literal asterisks\*

预览：

*this text is surrounded by literal asterisks*

行内代码#

HTML 标签：<code>

用反引号 (`) 包裹。

代码：

1
Use the `printf()` function.

预览：

Use the printf() function.

若行内代码中需要包含反引号字符，可使用多重反引号作为定界符：

代码：

1
``There is a literal backtick (`) here.``

预览：

There is a literal backtick (`) here.

行内代码两侧的定界符允许包含空格（开头一个、结尾一个），方便在代码起始或结尾放置反引号字符：

代码：

1
A single backtick in a code span: `` ` ``
2

3
A backtick-delimited string in a code span: `` `foo` ``

预览：

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

图片#

HTML 标签：<img />

Markdown 的图片语法与链接类似，支持行内与引用两种方式。

行内图片#

行内图片语法：![替代文本](URL "标题")

标题可选。

代码：

1
![Alt text](/path/to/img.jpg)
2

3
![Alt text](/path/to/img.jpg "Optional title")

预览：

Alt text

说明：

一个感叹号 !；
后接方括号，放置图片的替代文本；
再接圆括号，内含图片 URL/路径，及可选的标题（引号包裹）。

引用式图片#

引用式图片语法：![替代文本][id]

代码：

1
[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
2
![Alt text][img id]

预览：

Alt text

删除线#

HTML 标签：<del>

这是扩展语法。

GFM 增加了删除线语法。

代码：

1
~~Mistaken text.~~

预览：

Mistaken text.

杂项#

自动链接#

Markdown 支持一种便捷写法来创建“自动链接”（URL 与邮箱地址）：只需用尖括号将其包住即可。

代码：

1
<http://example.com/>
2

3
<address@example.com>

预览：

http://example.com/

address@example.com

GFM 会自动识别标准 URL 并转换为链接。

代码：

1
https://github.com/emn178/markdown

预览：

https://github.com/emn178/markdown

反斜杠转义#

Markdown 允许使用反斜杠来转义那些本用于 Markdown 语法的特殊字符，使其按字面显示。

代码：

1
\*literal asterisks\*

预览：

*literal asterisks*

以下字符可通过反斜杠转义以按字面量输出：

Code:

1
\   backslash
2
`   backtick
3
*   asterisk
4
_   underscore
5
{}  curly braces
6
[]  square brackets
7
()  parentheses
8
#   hash mark
9
+   plus sign
10
-   minus sign (hyphen)
11
.   dot
12
!   exclamation mark

内联 HTML#

对于 Markdown 语法未覆盖的标记，直接使用原生 HTML 即可。无需特别声明从 Markdown 切换到 HTML，直接写标签就行。

代码：

1
This is a regular paragraph.
2

3
<table>
4
    <tr>
5
        <td>Foo</td>
6
    </tr>
7
</table>
8

9
This is another regular paragraph.

预览：

This is a regular paragraph.

Foo

This is another regular paragraph.

请注意：在块级 HTML 标签内不会处理 Markdown 语法。

与块级标签不同，在行内级标签内会处理 Markdown 语法。

代码：

1
<span>**Work**</span>
2

3
<div>
4
    **No Work**
5
</div>

预览：

Work

**No Work**

*** ## Markdown 扩展功能

来源：src/content/posts/markdown-extended.md。了解 Firefly 中的 Markdown 功能

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

GitHub

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

展开收起

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

展开收起

Obsidian

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

展开收起

VitePress

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

展开收起

Docusaurus

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

您可以使用 [grid] 和 [/grid] 标签将多张图片纵向并排展示。这对于展示照片画廊或对比图非常有用。系统会自动根据包裹在其中的图片数量（最多支持并排展示4张）以响应式网格进行布局。

自动补齐图片高度： 同一排中如果有高度、大小或者比例不一的图片，会像「九宫格画廊相册」一样自动撑满。较短或不协调的图片会自动使用 object-cover 进行完美中心裁剪补充视野。图片边框水平彻底对齐无缝隙，但被裁剪后，只有点击图片通过灯箱才能查看完整图片，所以建议尽量避免使用长宽比例不一致的图片在同一排中。

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

示例图片一

示例图片二

基本语法

1
[grid]
2
![示例图片一](./images/firefly1.avif)
3
![示例图片二](./images/firefly2.avif)
4
![示例图片二](./images/firefly3.avif)
5
[/grid]

Firefly 代码块示例#

来源：src/content/posts/code-examples.md。在Firefly中使用表达性代码的代码块在 Markdown 中的外观。

在这里，我们将探索如何使用 Expressive Code 展示代码块。提供的示例基于官方文档，您可以参考以获取更多详细信息。

表达性代码#

语法高亮#

语法高亮

常规语法高亮#

1
console.log('此代码有语法高亮!')

渲染 ANSI 转义序列#

Terminal window展开收起

1
Standard ANSI colors:
2
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
3
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
4
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
5
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
6

7
8-bit colors (showing colors 160-171 as an example):
8
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
9
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
10
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
11
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 
12

13
24-bit colors (full RGB):
14
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
15
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
16
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
17
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
18

19
Font styles:
20
- Default
21
- Bold
22
- Dimmed
23
- Italic
24
- Underline
25
- Reversed
26
- Strikethrough

展开收起

编辑器和终端框架#

编辑器和终端框架

代码编辑器框架#

my-test-file.js

1
console.log('标题属性示例')

src/content/index.html

1
<div>文件名注释示例</div>

终端框架#

Terminal window

1
echo "此终端框架没有标题"

PowerShell 终端示例

1
Write-Output "这个有标题!"

覆盖框架类型#

1
echo "看，没有框架!"

PowerShell Profile.ps1

1
## 如果不覆盖，这将是一个终端框架
2
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
3
New-Alias tail Watch-Tail

文本和行标记#

文本和行标记

标记整行和行范围#

1
// 第1行 - 通过行号定位
2
// 第2行
3
// 第3行
4
// 第4行 - 通过行号定位
5
// 第5行
6
// 第6行
7
// 第7行 - 通过范围 "7-8" 定位
8
// 第8行 - 通过范围 "7-8" 定位

选择行标记类型 (mark, ins, del)#

line-markers.js

1
function demo() {
2
  console.log('此行标记为已删除')
3
  // 此行和下一行标记为已插入
4
  console.log('这是第二个插入行')
5

6
  return '此行使用中性默认标记类型'
7
}

为行标记添加标签#

labeled-line-markers.jsx

1
<button
2
  role="button"
3
  {...props}
4
  value={value}
5
  className={buttonClassName}
6
  disabled={disabled}
7
  active={active}
8
>
9
  {children &&
10
    !active &&
11
    (typeof children === 'string' ? <span>{children}</span> : children)}
12
</button>

在单独行上添加长标签#

labeled-line-markers.jsx展开收起

1
<button
2
  role="button"
3
  {...props}
4

5
  value={value}
6
  className={buttonClassName}
7

8
  disabled={disabled}
9
  active={active}
10
>
11

12
  {children &&
13
    !active &&
14
    (typeof children === 'string' ? <span>{children}</span> : children)}
15
</button>

展开收起

使用类似 diff 的语法#

1
此行将标记为已插入
2
此行将标记为已删除
3
这是常规行

1
--- a/README.md
2
+++ b/README.md
3
@@ -1,3 +1,4 @@
4
+this is an actual diff file
5
-all contents will remain unmodified
6
 no whitespace will be removed either

结合语法高亮和类似 diff 的语法#

1
function thisIsJavaScript() {
2
  // 整个块都会以 JavaScript 高亮显示，
3
  // 并且我们仍然可以为其添加 diff 标记！
4
  console.log('要删除的旧代码')
5
  console.log('新的闪亮代码！')
6
}

标记行内的单独文本#

1
function demo() {
2
  // 标记行内的任何给定文本
3
  return '支持给定文本的多个匹配项';
4
}

正则表达式#

1
console.log('单词 yes 和 yep 将被标记。')

转义正斜杠#

Terminal window

1
echo "Test" > /home/test.txt

选择内联标记类型 (mark, ins, del)#

1
function demo() {
2
  console.log('这些是插入和删除的标记类型');
3
  // return 语句使用默认标记类型
4
  return true;
5
}

自动换行#

自动换行

为每个块配置自动换行#

1
// 启用换行的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// wrap=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

配置换行的缩进#

1
// preserveIndent 示例（默认启用）
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// preserveIndent=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

可折叠部分#

可折叠部分


5 collapsed lines
1
// 所有这些样板设置代码将被折叠
2
import { someBoilerplateEngine } from '@example/some-boilerplate'
3
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
4

5
const engine = someBoilerplateEngine(evenMoreBoilerplate())
6

7
// 这部分代码默认可见
8
engine.doSomething(1, 2, 3, calcFn)
9

10
function calcFn() {
11
  // 您可以有多个折叠部分
3 collapsed lines
12
  const a = 1
13
  const b = 2
14
  const c = a + b
15

16
  // 这将保持可见
17
  console.log(`计算结果: ${a} + ${b} = ${c}`)
18
  return c
19
}
20

4 collapsed lines
21
// 直到块末尾的所有代码将再次被折叠
22
engine.closeConnection()
23
engine.freeMemory()
24
engine.shutdown({ reason: '示例样板代码结束' })

展开收起

行号#

行号

为每个块显示行号#

1
// 此代码块将显示行号
2
console.log('来自第2行的问候!')
3
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉，你知道我在第几行吗?')

更改起始行号#

5
console.log('来自第5行的问候!')
6
console.log('我在第6行')

KaTeX 数学公式示例#

来源：src/content/posts/katex-math-example.md。展示 Firefly 主题对 KaTeX 数学公式的支持，包括行内公式、块级公式和复杂数学符号。

本文展示了 Firefly 主题对 KaTeX 数学公式的渲染支持。

行内公式 (Inline)#

行内公式使用单个 $ 符号包裹。

例如：欧拉公式 eiπ+1=0e^{i\pi} + 1 = 0eiπ+1=0 是数学中最优美的公式之一。

质能方程 E=mc2E = mc^2E=mc2 也是家喻户晓。

块级公式 (Block)#

块级公式使用两个 $$ 符号包裹，会居中显示。

∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}∫−∞∞e−x2dx=πx=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}x=2a−b±b2−4ac

复杂示例#

矩阵 (Matrices)#

(abcd)(αβγδ)=(aα+bγaβ+bδcα+dγcβ+dδ)\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} \alpha & \beta \\ \gamma & \delta \end{pmatrix} = \begin{pmatrix} a\alpha + b\gamma & a\beta + b\delta \\ c\alpha + d\gamma & c\beta + d\delta \end{pmatrix}(acbd)(αγβδ)=(aα+bγcα+dγaβ+bδcβ+dδ)

极限与求和 (Limits and Sums)#

∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2lim⁡x→0sin⁡xx=1\lim_{x \to 0} \frac{\sin x}{x} = 1x→0limxsinx=1

麦克斯韦方程组 (Maxwell’s Equations)#

∇⋅E=ρε0∇⋅B=0∇×E=−∂B∂t∇×B=μ0J+μ0ε0∂E∂t\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\ \nabla \times \mathbf{B} &= \mu_0\mathbf{J} + \mu_0\varepsilon_0\frac{\partial \mathbf{E}}{\partial t} \end{aligned}∇⋅E∇⋅B∇×E∇×B=ε0ρ=0=−∂t∂B=μ0J+μ0ε0∂t∂E

化学方程式 (Chemical Equations)#

\ceCH4+2O2−>CO2+2H2O\ce{CH4 + 2O2 -> CO2 + 2H2O}\ceCH4+2O2−>CO2+2H2O

符号	代码	渲染结果
Alpha	`\alpha`	α\alphaα
Beta	`\beta`	β\betaβ
Gamma	`\Gamma`	Γ\GammaΓ
Pi	`\pi`	π\piπ
Infinity	`\infty`	∞\infty∞
Right Arrow	`\rightarrow`	→\rightarrow→
Partial	`\partial`	∂\partial∂

Markdown Mermaid 图表#

来源：src/content/posts/markdown-mermaid.md。一个包含 Mermaid 的 Markdown 博客文章简单示例。

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、甘特图、类图和状态图。

流程图示例#

流程图非常适合表示流程或算法步骤。

graph TD A[开始] --> B{条件检查} B -->|是| C[处理步骤 1] B -->|否| D[处理步骤 2] C --> E[子过程] D --> E subgraph E [子过程详情] E1[子步骤 1] --> E2[子步骤 2] E2 --> E3[子步骤 3] end E --> F{另一个决策} F -->|选项 1| G[结果 1] F -->|选项 2| H[结果 2] F -->|选项 3| I[结果 3] G --> J[结束] H --> J I --> J

时序图示例#

时序图显示对象之间随时间的交互。

sequenceDiagram participant User as 用户 participant WebApp as 网页应用 participant Server as 服务器 participant Database as 数据库 User->>WebApp: 提交登录请求 WebApp->>Server: 发送认证请求 Server->>Database: 查询用户凭据 Database-->>Server: 返回用户数据 Server-->>WebApp: 返回认证结果 alt 认证成功 WebApp->>User: 显示欢迎页面 WebApp->>Server: 请求用户数据 Server->>Database: 获取用户偏好 Database-->>Server: 返回偏好设置 Server-->>WebApp: 返回用户数据 WebApp->>User: 加载个性化界面 else 认证失败 WebApp->>User: 显示错误消息 WebApp->>User: 提示重新输入 end

甘特图示例#

甘特图非常适合显示项目进度和时间线。

gantt title 网站开发项目时间线 dateFormat YYYY-MM-DD axisFormat %m/%d section 设计阶段需求分析 :a1, 2023-10-01, 7d UI设计 :a2, after a1, 10d 原型创建 :a3, after a2, 5d section 开发阶段前端开发 :b1, 2023-10-20, 15d 后端开发 :b2, after a2, 18d 数据库设计 :b3, after a1, 12d section 测试阶段单元测试 :c1, after b1, 8d 集成测试 :c2, after b2, 10d 用户验收测试 :c3, after c2, 7d section 部署生产环境部署 :d1, after c3, 3d 发布 :milestone, after d1, 0d

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

classDiagram class User { +String username +String password +String email +Boolean active +login() +logout() +updateProfile() } class Article { +String title +String content +Date publishDate +Boolean published +publish() +edit() +delete() } class Comment { +String content +Date commentDate +addComment() +deleteComment() } class Category { +String name +String description +addArticle() +removeArticle() } User "1" -- "*" Article : 写作 User "1" -- "*" Comment : 发表 Article "1" -- "*" Comment : 拥有 Article "1" -- "*" Category : 属于

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

stateDiagram-v2 [*] --> 草稿草稿 --> 审核中 : 提交审核中 --> 草稿 : 拒绝审核中 --> 已批准 : 批准已批准 --> 已发布 : 发布已发布 --> 已归档 : 归档已发布 --> 草稿 : 撤回 state 已发布 { [*] --> 活跃活跃 --> 隐藏 : 临时隐藏隐藏 --> 活跃 : 恢复活跃 --> [*] 隐藏 --> [*] } 已归档 --> [*]

饼图示例#

饼图非常适合显示比例和百分比数据。

pie title 网站流量来源分析 "搜索引擎" : 45.6 "直接访问" : 30.1 "社交媒体" : 15.3 "推荐链接" : 6.4 "其他来源" : 2.6

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了如何使用流程图、时序图、甘特图、类图、状态图和饼图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。Mermaid 会自动将这些描述转换为美观的可视化图表。

尝试在您的下一篇技术博客文章或项目文档中使用 Mermaid 图表 - 它们将使您的内容更加专业且更易理解！

Markdown PlantUML 图表#

来源：src/content/posts/markdown-plantuml.md。用于验证 Firefly 中 PlantUML 插件渲染、主题切换与交互能力的示例文章。

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。

如果你想快速上手，可以记住这个最小模板：

活动图示例#

状态图示例#

用例图示例#

组件图示例#

部署图示例#

ER 图示例#

时序图示例（登录与刷新令牌）#

C4 风格容器图示例#

MDX 格式文章示例#

来源：src/content/posts/mdx-example.mdx。这是一个 MDX 格式的示例文章，展示了如何在 Markdown 中使用 JSX。

1
import { Icon } from 'astro-icon/components'

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

使用组件#

这是一个图标组件：

1
import { Icon } from 'astro-icon/components'
2

3
<div class="flex items-center gap-2 my-4">
4
  <Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
5
  <span>火箭发射！</span>
6
</div>

1
<div class="flex items-center gap-2 my-4">
2
  <Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
3
  <span>火箭发射！</span>
4
</div>

使用 JSX#

你也可以直接写 HTML/JSX：

1
<div className="p-4 bg-blue-100 dark:bg-blue-900 rounded-lg my-4">
2
  这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。
3
</div>

1
<div className="p-4 bg-blue-100 dark:bg-blue-900 rounded-lg my-4">
2
  这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。
3
</div>

简单的变量导出#

1
export const year = new Date().getFullYear()
2

3
今年是 {year} 年。

1
export const year = new Date().getFullYear()
2

3
今年是 {year} 年。

更多信息，请查看 MDX 文档

在文章中嵌入视频#

来源：src/content/posts/video.md。这篇文章演示如何在博客文章中嵌入视频。

只需从 YouTube 或其他平台复制嵌入代码，然后将其粘贴到 markdown 文件中。

1
---
2
title: 在文章中嵌入视频
3
published: 2023-10-19
4
// ...
5
---
6

7
<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube#

Bilibili#

## Firefly 文章加密

来源：src/content/posts/encrypted-demo.md。这是一篇密码保护的示例文章，用于演示文章加密功能。

成功解锁了这篇文章！#

如果你能看到这段内容，说明密码输入正确，文章已成功解密。

功能说明#

构建时加密：文章内容在构建时使用 AES-256-GCM 算法加密，页面源码中不包含任何明文。
客户端解密：访客输入正确密码后，浏览器通过 Web Crypto API 在本地完成解密。
会话缓存：同一浏览器会话内，密码会被缓存到 sessionStorage，刷新页面无需重复输入。
关闭即失效：关闭浏览器后缓存清除，再次访问需要重新输入密码。

密码为 TengJinCheng，仅供测试使用。

图片#

Firefly

GitHub 仓库卡片#

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

提示框#

NOTE

突出显示用户应该考虑的信息。

TIP

可选信息，帮助用户更成功。

自定义标题

这是一个带有自定义标题的示例。

数学公式#

行内公式 (Inline)#

欧拉公式 eiπ+1=0e^{i\pi} + 1 = 0eiπ+1=0 是数学中最优美的公式之一。

质能方程 E=mc2E = mc^2E=mc2 也是家喻户晓。

块级公式 (Block)#

块级公式使用两个 $$ 符号包裹，会居中显示。

∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}∫−∞∞e−x2dx=πx=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}x=2a−b±b2−4ac

化学方程式 (Chemical Equations)#

\ceCH4+2O2−>CO2+2H2O\ce{CH4 + 2O2 -> CO2 + 2H2O}\ceCH4+2O2−>CO2+2H2O

代码块#

常规语法高亮#

1
console.log('此代码有语法高亮!')

渲染 ANSI 转义序列#

Terminal window

1
ANSI colors:
2
- Regular: Red Green Yellow Blue Magenta Cyan
3
- Bold:    Red Green Yellow Blue Magenta Cyan
4
- Dimmed:  Red Green Yellow Blue Magenta Cyan
5

6
256 colors (showing colors 160-177):
7
160 161 162 163 164 165
8
166 167 168 169 170 171
9
172 173 174 175 176 177
10

11
Full RGB colors:
12
ForestGreen - RGB(34, 139, 34)
13

14
Text formatting: Bold Dimmed Italic Underline

流程图#

A/B 测试先定义指标

Fri, 10 Jul 2026 00:00:00 GMT

A/B 测试先定义指标#

A/B 测试不是把两个版本上线后随便看哪个数据高。没有提前定义指标和窗口，很容易事后挑对自己有利的结果。

数据分析里最容易出问题的地方，不是函数不会用，而是数据口径没有在一开始说清楚。一个步骤如果不能解释输入是什么、输出是什么、失败时怎么看，就很难放进稳定流程。

使用场景#

先定义主指标，比如点击率、转化率、留存率；再定义样本范围、实验时间和排除规则。实验期间不要随意改版本。

我会先准备一个小样本，保证可以人工检查结果。大表直接跑起来很快，但一旦结果不对，很难判断是代码错、字段错，还是数据本身脏。

最小代码#

1
summary = df.groupby("variant").agg(
2
    users=("user_id", "nunique"),
3
    conversions=("converted", "sum"),
4
)
5
summary["conversion_rate"] = summary["conversions"] / summary["users"]
6
print(summary)

检查结果#

行数是否符合预期，不能只看代码是否报错。
关键字段的类型、缺失值和唯一值数量是否合理。
输出结果能否用三到五行样本手工复算。
如果生成报表，要保留清洗前后的对账数字。

容易忽略的点#

容易忽略的是样本量和波动。样本太少时，短期差异可能只是随机波动，不适合立刻下结论。

最小验收样例#

我会用三行数据做一次手工验收：一行正常记录，一行边界记录，一行异常记录。代码跑完后，把输出和手工计算结果对照一遍，确认不是字段名写对了但口径理解错了。

如果这一步会进入日报、周报或正式报告，还要把输入行数、输出行数和被过滤的记录数写到日志里。数据处理的可信度，来自这些可以复查的中间证据。

小结#

A/B 测试先定义指标要解决的是一个可复查的数据处理问题。先定义口径，再写代码，最后用样本和统计结果验收，分析结果才站得住。

个人现金流比收益率更重要

Fri, 10 Jul 2026 00:00:00 GMT

个人现金流比收益率更重要#

很多投资讨论会把注意力放在收益率上，但普通人真正先出问题的往往是现金流。收益率再高，也不能解决短期账单、房租和突发支出。

这篇只讲普通人需要先弄明白的基础框架，不替代当地政策、合同文本、基金合同、招募说明书或监管公告。涉及办理、维权和投资决策时，最终仍要回到正式文件和经办机构。

为什么这件事重要#

现金流管理先看收入稳定性、固定支出、债务还款、应急金和保险保障。只有短期资金安全，才有资格承受长期投资波动。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

基金、股票这类资产价格会波动，不能用未来可能收益覆盖今天确定支出。急用钱不适合放进高波动资产。

我会把核对点写成可以执行的问题：记录在哪里查，金额怎么算，谁承担责任，什么时候能使用或退出。只要这些问题没有答案，就不要只听别人一句经验。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要把投资当成解决所有财务问题的入口。先控制负债、保留应急金、理解风险，再考虑长期资产配置。

资料来源#

收益的另一面是风险：认识基金投资风险

小结#

个人现金流比收益率更重要的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

定时任务时间不对先查时区

Fri, 10 Jul 2026 00:00:00 GMT

定时任务时间不对先查时区#

定时任务最常见的问题是“我以为它会在这个时间跑”。服务器时区、cron 环境和日志时间只要有一个没确认，就容易误判。

排查问题时最重要的是顺序。先确认现象，再缩小范围，最后动手修复；如果一上来就改配置，很容易把原始问题掩盖掉。

先确认现象#

先查系统时区和当前时间，再看 crontab 表达式。cron 的环境变量很少，脚本里最好使用绝对路径。

我会保留一条修复前命令，证明问题确实存在。这样修复后才能对比，而不是凭感觉判断。

排查命令#

Terminal window

1
date
2
timedatectl
3
crontab -l
4
grep CRON /var/log/cron | tail -n 20

处理原则#

涉及服务器时，先备份配置或确认回滚方式。
涉及进程时，先判断它是不是线上服务。
涉及删除时，先用 du、ls、日志确认对象。
修完后必须做业务层验证，不只看报错消失。

复盘记录#

复盘记录里要写任务实际触发时间、日志路径和失败通知方式。自动化任务没有日志，基本等于不可维护。

最小验收样例#

我会记录修复前后的两条命令输出。比如端口问题就保存监听状态，权限问题就保存文件权限，服务问题就保存状态和日志。没有对比证据，就很难说明问题确实被解决。

如果操作发生在服务器上，还要写明当前用户、工作目录和影响范围。排查文章不是命令收藏夹，而是下一次可以照着走的现场记录。

小结#

定时任务时间不对先查时区不是记一个命令，而是记一条排查链路。现象、命令、输出、验证都留下，下次才不用重新猜。

每日发布节奏如何自动化

Fri, 10 Jul 2026 00:00:00 GMT

每日发布节奏如何自动化#

自动化不是每天机械堆文章，而是把重复流程固定下来，把质量判断留在明确规则里。

我会把它当成一次站点维护记录来写：不仅说明要改什么，还要说明为什么改、怎么验证、失败时怎么回退。这样以后继续维护博客时，不需要重新摸索同一套流程。

先确定维护对象#

我会把流程拆成四步：确认当天缺哪些分类，生成每篇文章，运行质量检查，构建并验证线上 URL。任何一步失败，都不应该报告成功。

我会先把目标限定到一个很小的范围：是文章内容、frontmatter、图片、内链、搜索索引，还是线上发布流程。对象越清楚，越不容易把一次小修变成无边界重构。

操作步骤#

先在源码里定位相关文件，不直接改构建产物。
修改后检查标题、摘要、分类、标签和日期是否仍然一致。
本地或服务器构建通过后，再看 dist/api/allPostMeta.json 是否更新。
最后抽查真实 URL，不用“我觉得应该好了”代替线上验证。

可复制的检查命令#

Terminal window

1
node scripts/check-daily-coverage.mjs
2
pnpm build
3
curl -I https://blog.tjcheng.cn/api/allPostMeta.json

复盘标准#

复盘时最重要的是缺口统计和线上验证。文章源文件存在不代表页面已上线，必须看 allPostMeta.json 和 HTTP 200。

如果这篇文章以后还要扩展，我会优先补真实案例：修改前是什么样，改了哪个文件，构建日志里看到了什么，线上页面怎么确认。维护类文章只有落到证据上，才不是空泛经验。

小结#

每日发布节奏如何自动化的重点是把维护动作变成可验证流程。能定位、能修改、能构建、能线上确认，这篇笔记才有长期价值。

贪心算法处理区间选择

Fri, 10 Jul 2026 00:00:00 GMT

贪心算法处理区间选择#

贪心算法不是每一步随便选看起来最好的，而是要能证明局部选择不会破坏全局最优。

算法题真正要练的是把题目翻译成状态、边界和转移。模板可以帮助提速，但不能替代对条件的判断。

题型识别#

最多不重叠区间问题里，优先选择结束时间最早的区间。它给后续留下最多空间，因此是合理的局部选择。

遇到类似题时，我会先写一句话解释输入、输出和约束，再决定用什么结构。只要这一步说不清，直接写代码大概率会在边界条件上出错。

核心写法#

1
def max_non_overlap(intervals):
2
    intervals.sort(key=lambda x: x[1])
3
    ans = 0
4
    last_end = float('-inf')
5
    for start, end in intervals:
6
        if start >= last_end:
7
            ans += 1
8
            last_end = end
9
    return ans

边界样例#

空输入或只有一个元素时，答案应该是什么。
元素重复时，比较关系是否仍然成立。
结果需要下标、长度、数量，还是具体路径。
时间复杂度能不能从每个元素处理次数解释出来。

复盘#

复盘时要区分按开始时间排序和按结束时间排序。选错排序规则，样例少时可能过，复杂样例就会错。

最小验收样例#

我会至少准备三个样例：一个普通样例，一个边界样例，一个专门卡比较条件的样例。算法代码最怕只过了题目给的样例，却没有覆盖空输入、重复元素或极端顺序。

写完后不要只看答案，还要能解释每一步状态为什么变化。只要能把状态变化讲清楚，换一个题面时就不容易机械套错模板。

小结#

贪心算法处理区间选择的练习重点，是把固定套路拆成可解释的判断。能说明为什么这样维护状态，才算真正掌握。

图像训练集泄漏怎么发现

Fri, 10 Jul 2026 00:00:00 GMT

图像训练集泄漏怎么发现#

验证集指标很好，但真实图片效果差，可能是训练集和验证集泄漏。视觉任务里，相似图片泄漏特别常见。

计算机视觉流程不能只看终端输出。图片能不能读、标注是否对齐、可视化是否正常，往往比训练命令本身更早暴露问题。

先看输入#

视频抽帧、连拍图片、同一物体不同角度，如果随机按图片划分，很可能把高度相似样本分到 train 和 val 两边。

我会先选少量图片做检查：一张正常图、一张边界图、一张容易失败的图。小样本跑通以后，再扩大到完整数据集。

示例代码#

1
from pathlib import Path
2

3
# 实际项目可使用 imagehash 检查近似重复
4
files = sorted(Path("images").glob("*.jpg"))
5
print("images", len(files))
6
print("check split by source video or scene id")

可视化验收#

保存至少一张中间结果图，而不是只打印数组形状。
检查坐标顺序，确认没有把 x/y 和 w/h 混用。
抽查失败样本路径，避免批量流程悄悄跳过坏图。
如果结果要进入训练集，记录数据版本和处理脚本版本。

常见误差来源#

常见检查方法包括按视频、设备、场景或主体分组划分，再用感知哈希找重复或近似重复图片。

最小验收样例#

我会固定一组小样本作为回归检查集。每次改处理脚本或训练配置，都先跑这组样本，确认输出图片、标注框或预测结果没有出现明显退化。

视觉任务的验收不能只依赖成功退出码。最少要打开一张输出图，并把失败样本单独记录下来。这样后续定位问题时，能从具体图片回到具体处理步骤。

小结#

图像训练集泄漏怎么发现的关键是让每一步都有可视化证据。视觉任务最终要回到图像本身，不能只信日志和指标。

分类模型混淆矩阵怎么看

Thu, 09 Jul 2026 00:00:00 GMT

分类模型混淆矩阵怎么看#

分类准确率只给一个总数，但混淆矩阵能告诉你哪些类别互相混淆。对业务来说，错把 A 当 B 和错把 B 当 A 的代价可能完全不同。

计算机视觉流程不能只看终端输出。图片能不能读、标注是否对齐、可视化是否正常，往往比训练命令本身更早暴露问题。

先看输入#

我会先看对角线，再看非对角线里数值最大的格子。那里通常代表模型最分不清的类别组合。

我会先选少量图片做检查：一张正常图、一张边界图、一张容易失败的图。小样本跑通以后，再扩大到完整数据集。

示例代码#

1
from sklearn.metrics import confusion_matrix
2

3
cm = confusion_matrix(y_true, y_pred, labels=class_names)
4
print(cm)
5
# 再配合 heatmap 可视化查看高混淆类别

可视化验收#

保存至少一张中间结果图，而不是只打印数组形状。
检查坐标顺序，确认没有把 x/y 和 w/h 混用。
抽查失败样本路径，避免批量流程悄悄跳过坏图。
如果结果要进入训练集，记录数据版本和处理脚本版本。

常见误差来源#

常见误差来自类别样本不平衡、标注边界模糊、训练集和验证集分布不一致。

最小验收样例#

我会固定一组小样本作为回归检查集。每次改处理脚本或训练配置，都先跑这组样本，确认输出图片、标注框或预测结果没有出现明显退化。

小结#

分类模型混淆矩阵怎么看的关键是让每一步都有可视化证据。视觉任务最终要回到图像本身，不能只信日志和指标。

动态规划先定义状态

Thu, 09 Jul 2026 00:00:00 GMT

动态规划先定义状态#

动态规划最难的不是写循环，而是定义状态。状态定义错了，转移方程再漂亮也没有意义。

算法题真正要练的是把题目翻译成状态、边界和转移。模板可以帮助提速，但不能替代对条件的判断。

题型识别#

我会按四步写：状态表示什么，初始值是什么，如何从旧状态转移，答案从哪里取。每一步都要能用自然语言解释。

遇到类似题时，我会先写一句话解释输入、输出和约束，再决定用什么结构。只要这一步说不清，直接写代码大概率会在边界条件上出错。

核心写法#

1
def climb_stairs(n):
2
    if n <= 2:
3
        return n
4
    dp = [0] * (n + 1)
5
    dp[1], dp[2] = 1, 2
6
    for i in range(3, n + 1):
7
        dp[i] = dp[i - 1] + dp[i - 2]
8
    return dp[n]

边界样例#

空输入或只有一个元素时，答案应该是什么。
元素重复时，比较关系是否仍然成立。
结果需要下标、长度、数量，还是具体路径。
时间复杂度能不能从每个元素处理次数解释出来。

复盘#

复盘时先用小样例手算表格，再对照代码输出。只看最终答案，很难发现中间状态偏移。

最小验收样例#

写完后不要只看答案，还要能解释每一步状态为什么变化。只要能把状态变化讲清楚，换一个题面时就不容易机械套错模板。

小结#

动态规划先定义状态的练习重点，是把固定套路拆成可解释的判断。能说明为什么这样维护状态，才算真正掌握。

Notebook 要能从头运行

Thu, 09 Jul 2026 00:00:00 GMT

Notebook 要能从头运行#

Notebook 最常见的问题是靠交互状态运行。中间变量在内存里存在，但从头运行时却报错。

使用场景#

交付 Notebook 前，我会重启内核，从第一格运行到最后一格。所有输入路径、随机种子和依赖版本都要写清楚。

我会先准备一个小样本，保证可以人工检查结果。大表直接跑起来很快，但一旦结果不对，很难判断是代码错、字段错，还是数据本身脏。

最小代码#

1
import random
2
import numpy as np
3

4
random.seed(42)
5
np.random.seed(42)
6

7
# Kernel -> Restart & Run All 后仍应成功

检查结果#

行数是否符合预期，不能只看代码是否报错。
关键字段的类型、缺失值和唯一值数量是否合理。
输出结果能否用三到五行样本手工复算。
如果生成报表，要保留清洗前后的对账数字。

容易忽略的点#

不要把探索阶段的临时输出全部保留。正式版本应该让读者看到数据来源、处理步骤、关键图表和结论。

最小验收样例#

小结#

Notebook 要能从头运行要解决的是一个可复查的数据处理问题。先定义口径，再写代码，最后用样本和统计结果验收，分析结果才站得住。

读者反馈要沉淀成问题清单

Thu, 09 Jul 2026 00:00:00 GMT

读者反馈要沉淀成问题清单#

读者反馈如果只停留在聊天记录里，很快就会丢失。真正有价值的反馈，应该进入一个可追踪的问题清单。

先确定维护对象#

我会把反馈分成错别字、代码失效、内容不清楚、页面问题和新选题五类。不同类型处理优先级不同，不能混在一起。

操作步骤#

先在源码里定位相关文件，不直接改构建产物。
修改后检查标题、摘要、分类、标签和日期是否仍然一致。
本地或服务器构建通过后，再看 dist/api/allPostMeta.json 是否更新。
最后抽查真实 URL，不用“我觉得应该好了”代替线上验证。

可复制的检查命令#

Terminal window

1
rg -n "TODO|FIXME|待补充" src/content/posts docs

复盘标准#

复盘时记录反馈来源、处理状态和修改链接。这样读者反馈会推动内容质量，而不是只带来临时打断。

小结#

读者反馈要沉淀成问题清单的重点是把维护动作变成可验证流程。能定位、能修改、能构建、能线上确认，这篇笔记才有长期价值。

工资条里的税前税后怎么看

Thu, 09 Jul 2026 00:00:00 GMT

工资条里的税前税后怎么看#

工资条里最容易混淆的是税前工资、应发工资、个人扣款、个税和实发工资。到手钱只是最后结果，不代表公司用工总成本。

为什么这件事重要#

税前收入通常先扣个人承担的社保、公积金等，再根据规则计算个税，最后得到实发工资。单位承担部分不会直接发给个人，但也是劳动关系成本的一部分。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

普通人应该核对月份、基本工资、绩效、补贴、社保公积金个人部分、个税和实发金额。发现异常时，先保留工资条和银行流水。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要只比较到手工资，也要看缴费基数、年终奖、补贴是否稳定、加班和福利是否写进正式制度。

小结#

工资条里的税前税后怎么看的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

大文件上传用 scp 还是 rsync

Thu, 09 Jul 2026 00:00:00 GMT

大文件上传用 scp 还是 rsync#

上传少量文件时，scp 简单直接；同步大量目录时，rsync 更容易控制差异和断点。

排查问题时最重要的是顺序。先确认现象，再缩小范围，最后动手修复；如果一上来就改配置，很容易把原始问题掩盖掉。

先确认现象#

如果是博客文章这种小文件，scp 足够；如果是构建产物、图片目录或备份包，rsync 的增量同步更稳。

我会保留一条修复前命令，证明问题确实存在。这样修复后才能对比，而不是凭感觉判断。

排查命令#

Terminal window

1
scp local.md blog-server:/www/wwwroot/blog_app/blog_web_app/src/content/posts/
2
rsync -av --delete --exclude node_modules ./dist/ blog-server:/tmp/dist-check/

处理原则#

涉及服务器时，先备份配置或确认回滚方式。
涉及进程时，先判断它是不是线上服务。
涉及删除时，先用 du、ls、日志确认对象。
修完后必须做业务层验证，不只看报错消失。

复盘记录#

复盘里要记录源路径、目标路径和排除规则。路径写错比工具选错更常见。

最小验收样例#

如果操作发生在服务器上，还要写明当前用户、工作目录和影响范围。排查文章不是命令收藏夹，而是下一次可以照着走的现场记录。

小结#

大文件上传用 scp 还是 rsync 不是记一个命令，而是记一条排查链路。现象、命令、输出、验证都留下，下次才不用重新猜。

相机标定先理解内参和畸变

Wed, 08 Jul 2026 00:00:00 GMT

相机标定先理解内参和畸变#

相机拍出来的图像不是完美针孔模型。镜头畸变、焦距、主点位置都会影响像素坐标和真实空间的对应关系。

计算机视觉流程不能只看终端输出。图片能不能读、标注是否对齐、可视化是否正常，往往比训练命令本身更早暴露问题。

先看输入#

标定前要拍多张不同角度的棋盘格图片，角点要清晰覆盖画面不同位置。图片太少、角度太单一，标定结果不稳定。

我会先选少量图片做检查：一张正常图、一张边界图、一张容易失败的图。小样本跑通以后，再扩大到完整数据集。

示例代码#

1
ret, corners = cv2.findChessboardCorners(gray, (9, 6), None)
2
if ret:
3
    cv2.drawChessboardCorners(img, (9, 6), corners, ret)
4
    cv2.imwrite("corners_check.jpg", img)

可视化验收#

保存至少一张中间结果图，而不是只打印数组形状。
检查坐标顺序，确认没有把 x/y 和 w/h 混用。
抽查失败样本路径，避免批量流程悄悄跳过坏图。
如果结果要进入训练集，记录数据版本和处理脚本版本。

常见误差来源#

常见误差来自棋盘格尺寸写错、角点检测失败却继续计算、标定后没有用重投影误差检查结果。

最小验收样例#

我会固定一组小样本作为回归检查集。每次改处理脚本或训练配置，都先跑这组样本，确认输出图片、标注框或预测结果没有出现明显退化。

小结#

相机标定先理解内参和畸变的关键是让每一步都有可视化证据。视觉任务最终要回到图像本身，不能只信日志和指标。

服务器端口不通先查防火墙

Wed, 08 Jul 2026 00:00:00 GMT

服务器端口不通先查防火墙#

服务启动了但外部访问不到，原因可能是程序没监听，也可能是系统防火墙或云安全组没放行。

排查问题时最重要的是顺序。先确认现象，再缩小范围，最后动手修复；如果一上来就改配置，很容易把原始问题掩盖掉。

先确认现象#

先在服务器本机查端口是否监听，再从外部测试端口连通性。只有确认进程监听后，才继续看防火墙和安全组。

我会保留一条修复前命令，证明问题确实存在。这样修复后才能对比，而不是凭感觉判断。

排查命令#

Terminal window

1
ss -lntp | grep ':8080'
2
firewall-cmd --list-ports 2>/dev/null || true
3
iptables -S | head
4
curl -I http://127.0.0.1:8080

处理原则#

涉及服务器时，先备份配置或确认回滚方式。
涉及进程时，先判断它是不是线上服务。
涉及删除时，先用 du、ls、日志确认对象。
修完后必须做业务层验证，不只看报错消失。

复盘记录#

复盘里要写清端口用途、协议 TCP/UDP、监听地址是 127.0.0.1 还是 0.0.0.0。

最小验收样例#

如果操作发生在服务器上，还要写明当前用户、工作目录和影响范围。排查文章不是命令收藏夹，而是下一次可以照着走的现场记录。

小结#

服务器端口不通先查防火墙不是记一个命令，而是记一条排查链路。现象、命令、输出、验证都留下，下次才不用重新猜。

堆处理 TopK 高频元素

Wed, 08 Jul 2026 00:00:00 GMT

堆处理 TopK 高频元素#

TopK 问题的核心是只保留当前最有价值的 k 个候选。数据量大时，全部排序可能不是最合适的选择。

算法题真正要练的是把题目翻译成状态、边界和转移。模板可以帮助提速，但不能替代对条件的判断。

题型识别#

先统计频次，再维护一个大小为 k 的小根堆。堆顶是当前 TopK 里频次最低的元素，遇到更高频元素就替换。

遇到类似题时，我会先写一句话解释输入、输出和约束，再决定用什么结构。只要这一步说不清，直接写代码大概率会在边界条件上出错。

核心写法#

1
from collections import Counter
2
import heapq
3

4
def top_k_frequent(nums, k):
5
    heap = []
6
    for num, freq in Counter(nums).items():
7
        heapq.heappush(heap, (freq, num))
8
        if len(heap) > k:
9
            heapq.heappop(heap)
10
    return [num for freq, num in heap]

边界样例#

空输入或只有一个元素时，答案应该是什么。
元素重复时，比较关系是否仍然成立。
结果需要下标、长度、数量，还是具体路径。
时间复杂度能不能从每个元素处理次数解释出来。

复盘#

复盘时要区分求最大 k 个、最小 k 个、频次 TopK 还是数值 TopK。比较键不同，堆里保存的结构也不同。

最小验收样例#

写完后不要只看答案，还要能解释每一步状态为什么变化。只要能把状态变化讲清楚，换一个题面时就不容易机械套错模板。

小结#

堆处理 TopK 高频元素的练习重点，是把固定套路拆成可解释的判断。能说明为什么这样维护状态，才算真正掌握。

异常值先报告不要急着删除

Wed, 08 Jul 2026 00:00:00 GMT

异常值先报告不要急着删除#

异常值不一定是错误。它可能是真实的大客户订单，也可能是录入错误。没有判断依据就删除，会让分析结果失真。

使用场景#

我会先输出异常样本表，保留原始 ID 和关键字段，再写处理建议。只有确认是错误数据，才进入修正或剔除流程。

我会先准备一个小样本，保证可以人工检查结果。大表直接跑起来很快，但一旦结果不对，很难判断是代码错、字段错，还是数据本身脏。

最小代码#

1
q1 = df["amount"].quantile(0.25)
2
q3 = df["amount"].quantile(0.75)
3
iqr = q3 - q1
4
high = q3 + 1.5 * iqr
5
outliers = df[df["amount"] > high]
6
outliers.to_excel("outliers_review.xlsx", index=False)

检查结果#

行数是否符合预期，不能只看代码是否报错。
关键字段的类型、缺失值和唯一值数量是否合理。
输出结果能否用三到五行样本手工复算。
如果生成报表，要保留清洗前后的对账数字。

容易忽略的点#

异常值报告要包含规则、数量、占比、样本和处理建议。否则别人看不到你为什么这样处理。

最小验收样例#

小结#

异常值先报告不要急着删除要解决的是一个可复查的数据处理问题。先定义口径，再写代码，最后用样本和统计结果验收，分析结果才站得住。

搜索关键词应该写进摘要里

Wed, 08 Jul 2026 00:00:00 GMT

搜索关键词应该写进摘要里#

站内搜索不是魔法。文章标题、摘要和正文开头如果没有出现关键术语，读者很难通过搜索找到它。

先确定维护对象#

我会把最重要的技术词放在标题或摘要里，比如 pandas merge、Nginx 403、YOLO 标注。但不要堆关键词，要自然说明问题。

操作步骤#

先在源码里定位相关文件，不直接改构建产物。
修改后检查标题、摘要、分类、标签和日期是否仍然一致。
本地或服务器构建通过后，再看 dist/api/allPostMeta.json 是否更新。
最后抽查真实 URL，不用“我觉得应该好了”代替线上验证。

可复制的检查命令#

Terminal window

1
curl -s https://blog.tjcheng.cn/api/allPostMeta.json | grep -i "pandas" | head

复盘标准#

复盘时用新文章标题里的关键词搜一次。如果搜不到，就检查 Pagefind 是否重建、文章是否进入 allPostMeta.json。

小结#

搜索关键词应该写进摘要里的重点是把维护动作变成可验证流程。能定位、能修改、能构建、能线上确认，这篇笔记才有长期价值。

社会结构里学历、城市和行业的作用

Wed, 08 Jul 2026 00:00:00 GMT

社会结构里学历、城市和行业的作用#

谈社会结构不是为了制造焦虑，而是为了理解机会为什么分布不均。学历、城市、行业、家庭资源和信息渠道都会影响一个人的选择空间。

为什么这件事重要#

学历常常影响第一轮筛选，城市影响岗位密度和公共资源，行业影响收入上限和周期波动。它们都重要，但都不是单一决定因素。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

普通人更应该关心可行动变量：提升技能、积累作品、寻找信息源、理解行业周期、控制负债和保持迁移能力。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要把个体努力和结构因素对立起来。结构解释限制，行动寻找突破口；只谈任何一边都容易失真。

小结#

社会结构里学历、城市和行业的作用的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

博客备份要做恢复演练

Tue, 07 Jul 2026 00:00:00 GMT

博客备份要做恢复演练#

很多人有备份，但从没恢复过。真正出事时才发现备份不完整、路径不对、权限不对，或者缺少构建依赖。

先确定维护对象#

博客备份至少包括文章源文件、构建产物、配置文件和部署脚本。恢复演练可以在临时目录做，不必影响线上站点。

操作步骤#

先在源码里定位相关文件，不直接改构建产物。
修改后检查标题、摘要、分类、标签和日期是否仍然一致。
本地或服务器构建通过后，再看 dist/api/allPostMeta.json 是否更新。
最后抽查真实 URL，不用“我觉得应该好了”代替线上验证。

可复制的检查命令#

Terminal window

1
tar -czf blog-posts-backup.tgz src/content/posts
2
mkdir -p /tmp/blog-restore-test
3
tar -xzf blog-posts-backup.tgz -C /tmp/blog-restore-test

复盘标准#

复盘时记录恢复步骤和耗时。一个好的备份方案，应该能回答：文件在哪里、怎么恢复、恢复后怎么验证。

小结#

博客备份要做恢复演练的重点是把维护动作变成可验证流程。能定位、能修改、能构建、能线上确认，这篇笔记才有长期价值。

部署时环境变量文件怎么检查

Tue, 07 Jul 2026 00:00:00 GMT

部署时环境变量文件怎么检查#

部署问题里，经常出现本地正常、服务器异常。原因可能不是代码，而是服务器的环境变量和本地不一致。

排查问题时最重要的是顺序。先确认现象，再缩小范围，最后动手修复；如果一上来就改配置，很容易把原始问题掩盖掉。

先确认现象#

先确认程序实际读取哪个 .env 文件，再确认服务进程是否重启。修改文件但不重启，运行中的进程通常不会自动拿到新值。

我会保留一条修复前命令，证明问题确实存在。这样修复后才能对比，而不是凭感觉判断。

排查命令#

Terminal window

1
printenv | sort | grep -E 'NODE_ENV|API|DATABASE'
2
systemctl show myapp --property=Environment
3
journalctl -u myapp -n 80 --no-pager

处理原则#

涉及服务器时，先备份配置或确认回滚方式。
涉及进程时，先判断它是不是线上服务。
涉及删除时，先用 du、ls、日志确认对象。
修完后必须做业务层验证，不只看报错消失。

复盘记录#

复盘记录里不要写真实密钥，只写变量名、配置位置和验证方式。敏感值不要放进博客和 Git。

最小验收样例#

如果操作发生在服务器上，还要写明当前用户、工作目录和影响范围。排查文章不是命令收藏夹，而是下一次可以照着走的现场记录。

小结#

部署时环境变量文件怎么检查不是记一个命令，而是记一条排查链路。现象、命令、输出、验证都留下，下次才不用重新猜。

图表类型不要随手选

Tue, 07 Jul 2026 00:00:00 GMT

图表类型不要随手选#

图表不是为了让报告好看，而是为了回答问题。图表类型选错，会让读者误解数据关系。

使用场景#

时间趋势优先用折线图，类别比较常用柱状图，两个连续变量关系适合散点图，分布和异常值可以用箱线图。

我会先准备一个小样本，保证可以人工检查结果。大表直接跑起来很快，但一旦结果不对，很难判断是代码错、字段错，还是数据本身脏。

最小代码#

1
import matplotlib.pyplot as plt
2

3
summary = df.groupby("month")["amount"].sum()
4
ax = summary.plot(kind="line", marker="o")
5
ax.set_title("Monthly Amount")
6
ax.set_xlabel("Month")
7
ax.set_ylabel("Amount")
8
plt.tight_layout()
9
plt.savefig("monthly_amount.png", dpi=150)

检查结果#

行数是否符合预期，不能只看代码是否报错。
关键字段的类型、缺失值和唯一值数量是否合理。
输出结果能否用三到五行样本手工复算。
如果生成报表，要保留清洗前后的对账数字。

容易忽略的点#

画图前先写一句话：这张图想证明什么。如果写不出来，说明还没到画图阶段。

最小验收样例#

小结#

图表类型不要随手选要解决的是一个可复查的数据处理问题。先定义口径，再写代码，最后用样本和统计结果验收，分析结果才站得住。

小目标检测先查分辨率和标注

Tue, 07 Jul 2026 00:00:00 GMT

小目标检测先查分辨率和标注#

小目标检测差，不一定是模型不够大。很多时候是输入尺寸太小、标注框不准、训练集里小目标样本太少。

计算机视觉流程不能只看终端输出。图片能不能读、标注是否对齐、可视化是否正常，往往比训练命令本身更早暴露问题。

先看输入#

先统计目标框面积占图片面积的比例，看看小目标到底有多少。再抽查小目标标注是否贴合，是否存在漏标。

我会先选少量图片做检查：一张正常图、一张边界图、一张容易失败的图。小样本跑通以后，再扩大到完整数据集。

示例代码#

1
areas = []
2
for box in boxes:
3
    x1, y1, x2, y2 = box
4
    areas.append((x2 - x1) * (y2 - y1) / (img_w * img_h))
5
print(min(areas), sum(a < 0.01 for a in areas))

可视化验收#

保存至少一张中间结果图，而不是只打印数组形状。
检查坐标顺序，确认没有把 x/y 和 w/h 混用。
抽查失败样本路径，避免批量流程悄悄跳过坏图。
如果结果要进入训练集，记录数据版本和处理脚本版本。

常见误差来源#

常见误差来自 resize 后目标只剩几个像素、增强时把小目标裁掉、验证集小目标数量太少导致指标不稳定。

最小验收样例#

我会固定一组小样本作为回归检查集。每次改处理脚本或训练配置，都先跑这组样本，确认输出图片、标注框或预测结果没有出现明显退化。

小结#

小目标检测先查分辨率和标注的关键是让每一步都有可视化证据。视觉任务最终要回到图像本身，不能只信日志和指标。

股票不是彩票：买股票买的是什么

Tue, 07 Jul 2026 00:00:00 GMT

股票不是彩票：买股票买的是什么#

很多人第一次接触股票时，只看到价格涨跌，容易把它当成短期猜数字游戏。其实股票背后对应的是上市公司权益和市场交易价格。

为什么这件事重要#

买股票不是买确定收益，而是在承担企业经营、市场波动、流动性、情绪和政策等多种风险。价格短期可能大幅波动，不能把历史涨幅当成未来承诺。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

普通人至少要区分公司基本面、市场估值、交易规则和个人资金安排。看不懂财报、不了解风险承受能力时，不要用急用钱参与高波动交易。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要相信稳赚、内幕、带单、保本高收益这类说法。公开市场投资最先要学的是风险边界。

资料来源#

小结#

股票不是彩票：买股票买的是什么的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

并查集处理连通关系

Tue, 07 Jul 2026 00:00:00 GMT

并查集处理连通关系#

并查集适合处理动态连通性问题。比如判断两个节点是否在同一集合，或者把若干关系逐步合并。

算法题真正要练的是把题目翻译成状态、边界和转移。模板可以帮助提速，但不能替代对条件的判断。

题型识别#

核心操作只有两个：find 找代表节点，union 合并两个集合。路径压缩能让后续查询更快。

遇到类似题时，我会先写一句话解释输入、输出和约束，再决定用什么结构。只要这一步说不清，直接写代码大概率会在边界条件上出错。

核心写法#

1
class DSU:
2
    def __init__(self, n):
3
        self.parent = list(range(n))
4

5
    def find(self, x):
6
        if self.parent[x] != x:
7
            self.parent[x] = self.find(self.parent[x])
8
        return self.parent[x]
9

10
    def union(self, a, b):
11
        ra, rb = self.find(a), self.find(b)
12
        if ra != rb:
13
            self.parent[rb] = ra

边界样例#

空输入或只有一个元素时，答案应该是什么。
元素重复时，比较关系是否仍然成立。
结果需要下标、长度、数量，还是具体路径。
时间复杂度能不能从每个元素处理次数解释出来。

复盘#

复盘时要注意并查集不擅长删除边。如果题目有频繁删除关系，要考虑其他结构或离线处理。

最小验收样例#

写完后不要只看答案，还要能解释每一步状态为什么变化。只要能把状态变化讲清楚，换一个题面时就不容易机械套错模板。

小结#

并查集处理连通关系的练习重点，是把固定套路拆成可解释的判断。能说明为什么这样维护状态，才算真正掌握。

分类页质量复查清单

Mon, 06 Jul 2026 00:00:00 GMT

分类页质量复查清单#

分类页是读者按主题找文章的入口。分类名称显示不完整、数量不对或点击后 404，都会让内容体系看起来不可信。

先确定维护对象#

我会先核对分类来自真实 frontmatter，而不是手写列表。新增分类后，分类页应该自动出现，文章数量和 allPostMeta.json 里的统计要一致。

操作步骤#

先在源码里定位相关文件，不直接改构建产物。
修改后检查标题、摘要、分类、标签和日期是否仍然一致。
本地或服务器构建通过后，再看 dist/api/allPostMeta.json 是否更新。
最后抽查真实 URL，不用“我觉得应该好了”代替线上验证。

可复制的检查命令#

Terminal window

1
curl -s https://blog.tjcheng.cn/api/allPostMeta.json | head
2
curl -I https://blog.tjcheng.cn/categories/

复盘标准#

复盘时除了看桌面端，也要看移动端。中文分类名称如果被省略到看不懂，就应该调整布局，而不是让读者猜。

小结#

分类页质量复查清单的重点是把维护动作变成可验证流程。能定位、能修改、能构建、能线上确认，这篇笔记才有长期价值。

数据字典先于分析代码

Mon, 06 Jul 2026 00:00:00 GMT

数据字典先于分析代码#

很多分析争议不是代码造成的，而是大家对字段含义理解不同。一个字段叫 amount，可能是含税金额、实付金额、优惠前金额，也可能是退款后的净额。

使用场景#

数据字典至少要写字段名、中文含义、类型、单位、缺失含义、枚举值和来源系统。写完以后，再开始做清洗和统计。

我会先准备一个小样本，保证可以人工检查结果。大表直接跑起来很快，但一旦结果不对，很难判断是代码错、字段错，还是数据本身脏。

最小代码#

1
field: amount
2
name: 实付金额
3
type: decimal
4
unit: yuan
5
missing: unknown
6
source: order_system.payment_amount

检查结果#

行数是否符合预期，不能只看代码是否报错。
关键字段的类型、缺失值和唯一值数量是否合理。
输出结果能否用三到五行样本手工复算。
如果生成报表，要保留清洗前后的对账数字。

容易忽略的点#

容易忽略的是单位和时间口径。金额是元还是分，日期是下单时间还是支付时间，都会改变结果解释。

最小验收样例#

小结#

数据字典先于分析代码要解决的是一个可复查的数据处理问题。先定义口径，再写代码，最后用样本和统计结果验收，分析结果才站得住。

基金风险等级怎么读

Mon, 06 Jul 2026 00:00:00 GMT

基金风险等级怎么读#

基金不是一个风险相同的产品类别。货币基金、债券基金、混合基金、股票基金、指数基金、私募基金的风险来源和波动程度都不一样。

为什么这件事重要#

基金销售里常见风险等级从低到高划分。普通人不应该只看历史收益，更要看产品类型、投资范围、封闭期、流动性和自己的风险承受能力。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

买基金前至少读基金合同、招募说明书、产品资料概要和风险揭示。看不懂时，不要因为别人推荐或短期涨幅就买。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要把“基金经理专业”理解成“不会亏钱”。基金仍然会受到市场、流动性、管理和特有风险影响。

资料来源#

小结#

基金风险等级怎么读的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

OCR 前的图像预处理顺序

Mon, 06 Jul 2026 00:00:00 GMT

OCR 前的图像预处理顺序#

OCR 识别效果不好时，不一定是识别模型差，可能是输入图片太脏。文字模糊、背景复杂、倾斜和光照不均都会影响结果。

计算机视觉流程不能只看终端输出。图片能不能读、标注是否对齐、可视化是否正常，往往比训练命令本身更早暴露问题。

先看输入#

我会先保留原图，再尝试灰度化、去噪、阈值分割和裁剪。每一步都保存中间图，确认文字没有被处理掉。

我会先选少量图片做检查：一张正常图、一张边界图、一张容易失败的图。小样本跑通以后，再扩大到完整数据集。

示例代码#

1
img = cv2.imread("page.jpg")
2
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
3
blur = cv2.GaussianBlur(gray, (3, 3), 0)
4
_, mask = cv2.threshold(blur, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
5
cv2.imwrite("ocr_preprocess.png", mask)

可视化验收#

保存至少一张中间结果图，而不是只打印数组形状。
检查坐标顺序，确认没有把 x/y 和 w/h 混用。
抽查失败样本路径，避免批量流程悄悄跳过坏图。
如果结果要进入训练集，记录数据版本和处理脚本版本。

常见误差来源#

常见误差来自阈值太狠导致细字断裂，或者为了去背景把标点、数字和小字号文字也抹掉。

最小验收样例#

我会固定一组小样本作为回归检查集。每次改处理脚本或训练配置，都先跑这组样本，确认输出图片、标注框或预测结果没有出现明显退化。

小结#

OCR 前的图像预处理顺序的关键是让每一步都有可视化证据。视觉任务最终要回到图像本身，不能只信日志和指标。

构建时内存不足怎么判断

Mon, 06 Jul 2026 00:00:00 GMT

构建时内存不足怎么判断#

前端静态站构建时，如果服务器内存不足，表现可能是进程被杀、长时间卡住，或者 SSH 响应变慢。

排查问题时最重要的是顺序。先确认现象，再缩小范围，最后动手修复；如果一上来就改配置，很容易把原始问题掩盖掉。

先确认现象#

先看 free -h、dmesg 和构建日志。如果出现 OOM killer 记录，就不是代码语法问题，而是资源问题。

我会保留一条修复前命令，证明问题确实存在。这样修复后才能对比，而不是凭感觉判断。

排查命令#

Terminal window

1
free -h
2
swapon --show
3
dmesg -T | grep -i 'killed process\|out of memory' | tail -n 20
4
NODE_OPTIONS=--max-old-space-size=1536 pnpm build

处理原则#

涉及服务器时，先备份配置或确认回滚方式。
涉及进程时，先判断它是不是线上服务。
涉及删除时，先用 du、ls、日志确认对象。
修完后必须做业务层验证，不只看报错消失。

复盘记录#

复盘时要记录 Node 版本、构建命令、内存峰值和是否使用 swap。不要长期依赖 swap 掩盖内存不足，但它可以让小服务器完成构建。

最小验收样例#

如果操作发生在服务器上，还要写明当前用户、工作目录和影响范围。排查文章不是命令收藏夹，而是下一次可以照着走的现场记录。

小结#

构建时内存不足怎么判断不是记一个命令，而是记一条排查链路。现象、命令、输出、验证都留下，下次才不用重新猜。

拓扑排序判断课程顺序

Mon, 06 Jul 2026 00:00:00 GMT

拓扑排序判断课程顺序#

当任务之间存在先后依赖时，可以把问题看成有向图。拓扑排序用来判断是否能找到一个合法顺序。

算法题真正要练的是把题目翻译成状态、边界和转移。模板可以帮助提速，但不能替代对条件的判断。

题型识别#

先统计每个节点入度，把入度为 0 的节点放进队列。每取出一个节点，就把它指向的后继入度减一，新的入度 0 节点继续入队。

遇到类似题时，我会先写一句话解释输入、输出和约束，再决定用什么结构。只要这一步说不清，直接写代码大概率会在边界条件上出错。

核心写法#

1
from collections import deque, defaultdict
2

3
def can_finish(n, edges):
4
    graph = defaultdict(list)
5
    indeg = [0] * n
6
    for a, b in edges:
7
        graph[b].append(a)
8
        indeg[a] += 1
9
    q = deque([i for i in range(n) if indeg[i] == 0])
10
    seen = 0
11
    while q:
12
        x = q.popleft()
13
        seen += 1
14
        for y in graph[x]:
15
            indeg[y] -= 1
16
            if indeg[y] == 0:
17
                q.append(y)
18
    return seen == n

展开收起

边界样例#

空输入或只有一个元素时，答案应该是什么。
元素重复时，比较关系是否仍然成立。
结果需要下标、长度、数量，还是具体路径。
时间复杂度能不能从每个元素处理次数解释出来。

复盘#

如果最后处理的节点数量少于总节点数，说明图里有环，无法完成所有依赖。

最小验收样例#

写完后不要只看答案，还要能解释每一步状态为什么变化。只要能把状态变化讲清楚，换一个题面时就不容易机械套错模板。

小结#

拓扑排序判断课程顺序的练习重点，是把固定套路拆成可解释的判断。能说明为什么这样维护状态，才算真正掌握。

图像增强策略要留记录

Sun, 05 Jul 2026 00:00:00 GMT

图像增强策略要留记录#

增强策略一旦改变，训练数据分布就变了。亮度、翻转、裁剪、旋转看起来只是预处理，实际会影响模型学到的特征。

计算机视觉流程不能只看终端输出。图片能不能读、标注是否对齐、可视化是否正常，往往比训练命令本身更早暴露问题。

先看输入#

我会记录每次增强的概率、参数范围和适用类别。方向敏感、文字识别、医学或工业场景不能随意套通用增强。

我会先选少量图片做检查：一张正常图、一张边界图、一张容易失败的图。小样本跑通以后，再扩大到完整数据集。

示例代码#

1
version: aug-v1
2
flip: horizontal, p=0.5
3
brightness: 0.8-1.2
4
crop: disabled
5
note: keep boxes synchronized

可视化验收#

保存至少一张中间结果图，而不是只打印数组形状。
检查坐标顺序，确认没有把 x/y 和 w/h 混用。
抽查失败样本路径，避免批量流程悄悄跳过坏图。
如果结果要进入训练集，记录数据版本和处理脚本版本。

常见误差来源#

常见误差来自增强图片但没有同步检测框，或者训练时使用随机增强却没有固定配置文件，导致结果无法复现。

最小验收样例#

我会固定一组小样本作为回归检查集。每次改处理脚本或训练配置，都先跑这组样本，确认输出图片、标注框或预测结果没有出现明显退化。

小结#

图像增强策略要留记录的关键是让每一步都有可视化证据。视觉任务最终要回到图像本身，不能只信日志和指标。

BFS 求网格最短路

Sun, 05 Jul 2026 00:00:00 GMT

BFS 求网格最短路#

网格最短路适合用 BFS，因为每一步代价相同，第一次到达终点时就是最短距离。

算法题真正要练的是把题目翻译成状态、边界和转移。模板可以帮助提速，但不能替代对条件的判断。

题型识别#

先把起点入队，记录访问状态和距离。每次从队列弹出一个格子，尝试向四个方向扩展，越界、障碍、已访问都跳过。

遇到类似题时，我会先写一句话解释输入、输出和约束，再决定用什么结构。只要这一步说不清，直接写代码大概率会在边界条件上出错。

核心写法#

1
from collections import deque
2

3
def shortest_path(grid):
4
    m, n = len(grid), len(grid[0])
5
    q = deque([(0, 0, 0)])
6
    seen = {(0, 0)}
7
    dirs = [(1,0), (-1,0), (0,1), (0,-1)]
8
    while q:
9
        x, y, d = q.popleft()
10
        if (x, y) == (m - 1, n - 1):
11
            return d
12
        for dx, dy in dirs:
13
            nx, ny = x + dx, y + dy
14
            if 0 <= nx < m and 0 <= ny < n and grid[nx][ny] == 0 and (nx, ny) not in seen:
15
                seen.add((nx, ny))
16
                q.append((nx, ny, d + 1))
17
    return -1

展开收起

边界样例#

空输入或只有一个元素时，答案应该是什么。
元素重复时，比较关系是否仍然成立。
结果需要下标、长度、数量，还是具体路径。
时间复杂度能不能从每个元素处理次数解释出来。

复盘#

复盘时要检查起点和终点是否可走，以及距离是从 0 开始还是从 1 开始。

最小验收样例#

写完后不要只看答案，还要能解释每一步状态为什么变化。只要能把状态变化讲清楚，换一个题面时就不容易机械套错模板。

小结#

BFS 求网格最短路的练习重点，是把固定套路拆成可解释的判断。能说明为什么这样维护状态，才算真正掌握。

博客图片压缩发布流程

Sun, 05 Jul 2026 00:00:00 GMT

博客图片压缩发布流程#

图片是博客最容易把页面拖慢的资源。尤其是截图和相册，如果原图直接上传，文章打开速度会明显下降。

先确定维护对象#

压缩前先确认图片用途。正文说明图不需要保留超大分辨率，关键细节图可以单独保留高清版本。文件名用英文和短横线，减少服务器路径问题。

操作步骤#

先在源码里定位相关文件，不直接改构建产物。
修改后检查标题、摘要、分类、标签和日期是否仍然一致。
本地或服务器构建通过后，再看 dist/api/allPostMeta.json 是否更新。
最后抽查真实 URL，不用“我觉得应该好了”代替线上验证。

可复制的检查命令#

Terminal window

1
find public -type f \( -name '*.png' -o -name '*.jpg' -o -name '*.webp' \) -size +1M -print

复盘标准#

复盘时看图片体积、加载状态和移动端显示。图片能显示只是最低标准，还要看它是否影响首屏加载。

小结#

博客图片压缩发布流程的重点是把维护动作变成可验证流程。能定位、能修改、能构建、能线上确认，这篇笔记才有长期价值。

Excel 多 Sheet 数据如何审查

Sun, 05 Jul 2026 00:00:00 GMT

Excel 多 Sheet 数据如何审查#

Excel 多 Sheet 文件经常把不同月份、部门或状态分开存放。直接拼接之前，必须确认每个 sheet 的字段结构是否一致。

使用场景#

先读取 sheet 名，再逐个检查行数和列名。不要默认每个 sheet 都是同一种表，有些文件会混入说明页、汇总页或空白页。

我会先准备一个小样本，保证可以人工检查结果。大表直接跑起来很快，但一旦结果不对，很难判断是代码错、字段错，还是数据本身脏。

最小代码#

1
xls = pd.ExcelFile("report.xlsx")
2
print(xls.sheet_names)
3
frames = []
4
for sheet in xls.sheet_names:
5
    df = pd.read_excel(xls, sheet_name=sheet)
6
    df["source_sheet"] = sheet
7
    print(sheet, df.shape, df.columns.tolist())
8
    frames.append(df)
9
all_data = pd.concat(frames, ignore_index=True)

检查结果#

行数是否符合预期，不能只看代码是否报错。
关键字段的类型、缺失值和唯一值数量是否合理。
输出结果能否用三到五行样本手工复算。
如果生成报表，要保留清洗前后的对账数字。

容易忽略的点#

合并时建议保留一个 source_sheet 字段。后续发现异常值时，可以追溯它来自哪个 sheet。

最小验收样例#

小结#

Excel 多 Sheet 数据如何审查要解决的是一个可复查的数据处理问题。先定义口径，再写代码，最后用样本和统计结果验收，分析结果才站得住。

住房公积金为什么说属于个人

Sun, 05 Jul 2026 00:00:00 GMT

住房公积金为什么说属于个人#

很多人只看到工资条里扣了公积金，却忽略了单位也会缴一部分。理解公积金时，要把缴存、账户归属和使用场景分开。

为什么这件事重要#

住房公积金由职工个人和单位按规则缴存，进入个人住房公积金账户。它有住房相关用途和提取规则，不等同于普通银行卡余额。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

普通人应该关注缴存基数、缴存比例、单位是否按月缴存、账户余额和当地提取/贷款规则。不同城市细则不同，不能直接套别人的经验。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要把公积金理解成“公司额外送的钱”。它是有制度规则和用途边界的长期住房储金，办理前要看当地公积金中心要求。

资料来源#

住房公积金管理条例

小结#

住房公积金为什么说属于个人的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

日志文件过大怎么处理

Sun, 05 Jul 2026 00:00:00 GMT

日志文件过大怎么处理#

服务器磁盘突然变满时，过大的日志文件经常是原因之一。但日志不能随便删，因为服务可能正在写入。

排查问题时最重要的是顺序。先确认现象，再缩小范围，最后动手修复；如果一上来就改配置，很容易把原始问题掩盖掉。

先确认现象#

先用 du 找大文件，再确认它属于哪个服务。短期止血可以截断日志，长期要配置 logrotate 或应用自己的日志轮转。

我会保留一条修复前命令，证明问题确实存在。这样修复后才能对比，而不是凭感觉判断。

排查命令#

Terminal window

1
du -h --max-depth=1 /var/log | sort -h
2
ls -lh /var/log/nginx
3
: > /var/log/nginx/error.log
4
logrotate -d /etc/logrotate.conf

处理原则#

涉及服务器时，先备份配置或确认回滚方式。
涉及进程时，先判断它是不是线上服务。
涉及删除时，先用 du、ls、日志确认对象。
修完后必须做业务层验证，不只看报错消失。

复盘记录#

复盘里要写清日志为什么暴涨：访问量、错误循环、调试级别、还是程序异常。只清理不找原因，问题会再次出现。

最小验收样例#

如果操作发生在服务器上，还要写明当前用户、工作目录和影响范围。排查文章不是命令收藏夹，而是下一次可以照着走的现场记录。

小结#

日志文件过大怎么处理不是记一个命令，而是记一条排查链路。现象、命令、输出、验证都留下，下次才不用重新猜。

训练前先画一批标注框

Sat, 04 Jul 2026 00:00:00 GMT

训练前先画一批标注框#

标注文件格式正确，不代表标注框一定正确。中心点、宽高、类别编号只要有一个含义混错，训练日志仍然可能正常跑完。

计算机视觉流程不能只看终端输出。图片能不能读、标注是否对齐、可视化是否正常，往往比训练命令本身更早暴露问题。

先看输入#

我会在训练前随机抽取几十张图片，把标签还原成像素坐标并画出来。尤其要看小目标、贴边目标、遮挡目标和多目标图片。

我会先选少量图片做检查：一张正常图、一张边界图、一张容易失败的图。小样本跑通以后，再扩大到完整数据集。

示例代码#

1
import cv2
2

3
# 伪代码：读取一行 YOLO 标注后还原
4
h, w = img.shape[:2]
5
cls, xc, yc, bw, bh = values
6
x1 = int((xc - bw / 2) * w)
7
y1 = int((yc - bh / 2) * h)
8
x2 = int((xc + bw / 2) * w)
9
y2 = int((yc + bh / 2) * h)
10
cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)

可视化验收#

保存至少一张中间结果图，而不是只打印数组形状。
检查坐标顺序，确认没有把 x/y 和 w/h 混用。
抽查失败样本路径，避免批量流程悄悄跳过坏图。
如果结果要进入训练集，记录数据版本和处理脚本版本。

常见误差来源#

常见误差来自归一化坐标没有乘回宽高、xywh 当成 xyxy、类别表顺序和标注工具导出顺序不一致。

最小验收样例#

我会固定一组小样本作为回归检查集。每次改处理脚本或训练配置，都先跑这组样本，确认输出图片、标注框或预测结果没有出现明显退化。

小结#

训练前先画一批标注框的关键是让每一步都有可视化证据。视觉任务最终要回到图像本身，不能只信日志和指标。

医保报销不是所有医疗费都报

Sat, 04 Jul 2026 00:00:00 GMT

医保报销不是所有医疗费都报#

很多人第一次住院才发现，医保不是把所有医疗费都按一个比例报销。医保有目录、起付线、封顶线、报销比例和异地结算等规则。

为什么这件事重要#

医保更像一套基本医疗保障制度，不是商业保险。它重点覆盖符合规则的医疗费用，不同地区、医院等级、参保类型可能影响实际报销。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

普通人应该提前知道自己的参保地、医保电子凭证、定点医疗机构、异地就医备案入口。真正生病时再临时查，容易手忙脚乱。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要把“能刷医保”理解成“全部报销”。自费药、目录外项目、起付线以内金额等，都可能由个人承担。

资料来源#

小结#

医保报销不是所有医疗费都报的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

博客文章内链怎么整理

Sat, 04 Jul 2026 00:00:00 GMT

博客文章内链怎么整理#

文章数量变多以后，读者不一定从首页进入，也不一定知道前后相关文章。内链的作用是把单篇笔记连接成路径。

先确定维护对象#

我会优先给系列文章加内链，比如 pandas 读取、清洗、统计、导出之间互相指向。内链文字要说明目标文章解决什么问题，不只写“点击这里”。

操作步骤#

先在源码里定位相关文件，不直接改构建产物。
修改后检查标题、摘要、分类、标签和日期是否仍然一致。
本地或服务器构建通过后，再看 dist/api/allPostMeta.json 是否更新。
最后抽查真实 URL，不用“我觉得应该好了”代替线上验证。

可复制的检查命令#

Terminal window

1
rg -n "\]\(/posts/|href=\"/posts" src/content/posts

复盘标准#

复盘时看两个指标：新文章是否指向旧文章，旧文章是否补了指向新文章的入口。只做单向链接，路径仍然不完整。

小结#

博客文章内链怎么整理的重点是把维护动作变成可验证流程。能定位、能修改、能构建、能线上确认，这篇笔记才有长期价值。

前缀和统计子数组数量

Sat, 04 Jul 2026 00:00:00 GMT

前缀和统计子数组数量#

前缀和适合处理连续区间求和。统计和为 k 的子数组时，关键是把区间和转化成两个前缀和之差。

算法题真正要练的是把题目翻译成状态、边界和转移。模板可以帮助提速，但不能替代对条件的判断。

题型识别#

遍历到当前位置时，当前前缀和是 s。如果之前出现过 s-k，说明从那个位置之后到当前位置的区间和是 k。

遇到类似题时，我会先写一句话解释输入、输出和约束，再决定用什么结构。只要这一步说不清，直接写代码大概率会在边界条件上出错。

核心写法#

1
from collections import defaultdict
2

3
def subarray_sum(nums, k):
4
    count = defaultdict(int)
5
    count[0] = 1
6
    s = 0
7
    ans = 0
8
    for x in nums:
9
        s += x
10
        ans += count[s - k]
11
        count[s] += 1
12
    return ans

边界样例#

空输入或只有一个元素时，答案应该是什么。
元素重复时，比较关系是否仍然成立。
结果需要下标、长度、数量，还是具体路径。
时间复杂度能不能从每个元素处理次数解释出来。

复盘#

复盘时要先把前缀和 0 放进计数表，表示从数组开头开始的区间也能被统计到。

最小验收样例#

写完后不要只看答案，还要能解释每一步状态为什么变化。只要能把状态变化讲清楚，换一个题面时就不容易机械套错模板。

小结#

前缀和统计子数组数量的练习重点，是把固定套路拆成可解释的判断。能说明为什么这样维护状态，才算真正掌握。

systemd 服务重启后怎么确认

Sat, 04 Jul 2026 00:00:00 GMT

systemd 服务重启后怎么确认#

服务重启成功不等于业务恢复。systemctl restart 只代表命令执行了，真正要看进程状态、端口监听和业务 URL。

排查问题时最重要的是顺序。先确认现象，再缩小范围，最后动手修复；如果一上来就改配置，很容易把原始问题掩盖掉。

先确认现象#

先看 systemctl status，再看最近日志，最后用端口或 HTTP 请求验证服务是否真的对外工作。不要只看 active 就结束。

我会保留一条修复前命令，证明问题确实存在。这样修复后才能对比，而不是凭感觉判断。

排查命令#

Terminal window

1
systemctl restart nginx
2
systemctl status nginx --no-pager
3
journalctl -u nginx -n 80 --no-pager
4
ss -lntp | grep ':80\|:443'

处理原则#

涉及服务器时，先备份配置或确认回滚方式。
涉及进程时，先判断它是不是线上服务。
涉及删除时，先用 du、ls、日志确认对象。
修完后必须做业务层验证，不只看报错消失。

复盘记录#

复盘记录里要写服务名、重启原因、重启时间和验证结果。线上服务最好在低峰期操作，并保留回滚方式。

最小验收样例#

如果操作发生在服务器上，还要写明当前用户、工作目录和影响范围。排查文章不是命令收藏夹，而是下一次可以照着走的现场记录。

小结#

systemd 服务重启后怎么确认不是记一个命令，而是记一条排查链路。现象、命令、输出、验证都留下，下次才不用重新猜。

时间序列 resample 前要检查什么

Sat, 04 Jul 2026 00:00:00 GMT

时间序列 resample 前要检查什么#

时间序列分析最怕日期列还没处理干净就开始按月汇总。日期格式、时区、重复时间点和缺失日期都会影响趋势判断。

使用场景#

resample 前先把日期列转成 datetime，并确认是否需要设置为索引。按日和按月统计的业务含义不同，不能只因为图好看就随便换粒度。

我会先准备一个小样本，保证可以人工检查结果。大表直接跑起来很快，但一旦结果不对，很难判断是代码错、字段错，还是数据本身脏。

最小代码#

1
df["date"] = pd.to_datetime(df["date"], errors="coerce")
2
ts = df.dropna(subset=["date"]).set_index("date").sort_index()
3
monthly = ts["amount"].resample("ME").sum()
4
print(monthly.tail())

检查结果#

行数是否符合预期，不能只看代码是否报错。
关键字段的类型、缺失值和唯一值数量是否合理。
输出结果能否用三到五行样本手工复算。
如果生成报表，要保留清洗前后的对账数字。

容易忽略的点#

注意 sum、mean、last 的含义完全不同。库存适合看期末值，销售额适合求和，温度可能适合平均。

最小验收样例#

小结#

时间序列 resample 前要检查什么要解决的是一个可复查的数据处理问题。先定义口径，再写代码，最后用样本和统计结果验收，分析结果才站得住。

博客 RSS 订阅入口检查

Fri, 03 Jul 2026 00:00:00 GMT

博客 RSS 订阅入口检查#

RSS 是给长期读者和订阅工具准备的入口。它不像首页那样显眼，但一旦失效，读者不会每天提醒你，只会慢慢收不到更新。

先确定维护对象#

RSS 检查的对象包括页脚链接、/rss.xml、文章标题、摘要和发布时间。新增文章后，RSS 应该能看到新条目，且链接指向正式文章页。

操作步骤#

先在源码里定位相关文件，不直接改构建产物。
修改后检查标题、摘要、分类、标签和日期是否仍然一致。
本地或服务器构建通过后，再看 dist/api/allPostMeta.json 是否更新。
最后抽查真实 URL，不用“我觉得应该好了”代替线上验证。

可复制的检查命令#

Terminal window

1
curl -I https://blog.tjcheng.cn/rss.xml
2
curl -s https://blog.tjcheng.cn/rss.xml | head -n 40

复盘标准#

复盘时我会记录 RSS 文件更新时间和最新文章标题。如果只检查页面不检查 RSS，就容易漏掉订阅用户的入口。

小结#

博客 RSS 订阅入口检查的重点是把维护动作变成可验证流程。能定位、能修改、能构建、能线上确认，这篇笔记才有长期价值。

图像数据集版本怎么记录

Fri, 03 Jul 2026 00:00:00 GMT

图像数据集版本怎么记录#

视觉模型结果变化时，很多人先怀疑模型参数，但真正原因经常是数据版本变了。图片、标签、划分文件和增强策略只要有一个变动，结果就不能直接比较。

计算机视觉流程不能只看终端输出。图片能不能读、标注是否对齐、可视化是否正常，往往比训练命令本身更早暴露问题。

先看输入#

我会给每次数据集变动写一个版本说明，记录图片数量、标签数量、类别分布、train/val 划分方式和清洗规则。版本名不要只叫 new，最好包含日期和目的。

我会先选少量图片做检查：一张正常图、一张边界图、一张容易失败的图。小样本跑通以后，再扩大到完整数据集。

示例代码#

1
from pathlib import Path
2

3
images = list(Path("images").rglob("*.jpg"))
4
labels = list(Path("labels").rglob("*.txt"))
5
print("images", len(images))
6
print("labels", len(labels))

可视化验收#

保存至少一张中间结果图，而不是只打印数组形状。
检查坐标顺序，确认没有把 x/y 和 w/h 混用。
抽查失败样本路径，避免批量流程悄悄跳过坏图。
如果结果要进入训练集，记录数据版本和处理脚本版本。

常见误差来源#

常见误差来自只复制图片不复制标签、删除坏图后没有同步划分文件、增强后覆盖原图、训练记录里没有写数据版本。

最小验收样例#

我会固定一组小样本作为回归检查集。每次改处理脚本或训练配置，都先跑这组样本，确认输出图片、标注框或预测结果没有出现明显退化。

小结#

图像数据集版本怎么记录的关键是让每一步都有可视化证据。视觉任务最终要回到图像本身，不能只信日志和指标。

Nginx 证书过期排查

Fri, 03 Jul 2026 00:00:00 GMT

Nginx 证书过期排查#

HTTPS 证书过期时，用户看到的是浏览器安全警告，但服务器上的网站文件可能完全正常。排查时要把证书问题和应用问题分开。

排查问题时最重要的是顺序。先确认现象，再缩小范围，最后动手修复；如果一上来就改配置，很容易把原始问题掩盖掉。

先确认现象#

先用浏览器或 openssl 看证书到期时间，再检查证书文件路径和 Nginx 配置是否一致。证书更新后还要 reload Nginx，不然进程可能仍然使用旧证书。

我会保留一条修复前命令，证明问题确实存在。这样修复后才能对比，而不是凭感觉判断。

排查命令#

Terminal window

1
echo | openssl s_client -servername blog.tjcheng.cn -connect blog.tjcheng.cn:443 2>/dev/null | openssl x509 -noout -dates
2
nginx -t
3
systemctl reload nginx

处理原则#

涉及服务器时，先备份配置或确认回滚方式。
涉及进程时，先判断它是不是线上服务。
涉及删除时，先用 du、ls、日志确认对象。
修完后必须做业务层验证，不只看报错消失。

复盘记录#

复盘记录里应该写清域名、证书路径、续签方式和 reload 时间。证书问题适合提前监控，不适合等用户反馈。

最小验收样例#

如果操作发生在服务器上，还要写明当前用户、工作目录和影响范围。排查文章不是命令收藏夹，而是下一次可以照着走的现场记录。

小结#

Nginx 证书过期排查不是记一个命令，而是记一条排查链路。现象、命令、输出、验证都留下，下次才不用重新猜。

pandas transform 做组内统计

Fri, 03 Jul 2026 00:00:00 GMT

pandas transform 做组内统计#

有些分析既要保留每一行明细，又要知道它所在组的统计值。groupby().agg() 会把数据压缩成汇总表，而 transform 可以把组内结果对齐回原表。

使用场景#

例如订单明细中想比较每笔订单是否高于本城市平均值，就适合用 transform。它返回的长度和原表一致，方便继续筛选、打标签和导出明细。

我会先准备一个小样本，保证可以人工检查结果。大表直接跑起来很快，但一旦结果不对，很难判断是代码错、字段错，还是数据本身脏。

最小代码#

1
df["city_avg"] = df.groupby("city")["amount"].transform("mean")
2
df["above_city_avg"] = df["amount"] > df["city_avg"]
3
print(df[["city", "amount", "city_avg", "above_city_avg"]].head())

检查结果#

行数是否符合预期，不能只看代码是否报错。
关键字段的类型、缺失值和唯一值数量是否合理。
输出结果能否用三到五行样本手工复算。
如果生成报表，要保留清洗前后的对账数字。

容易忽略的点#

transform 不适合生成多列复杂汇总。遇到多指标报表时，先用 agg 做汇总，再 merge 回明细，通常更清楚。

最小验收样例#

小结#

pandas transform 做组内统计要解决的是一个可复查的数据处理问题。先定义口径，再写代码，最后用样本和统计结果验收，分析结果才站得住。

养老保险缴费年限怎么看

Fri, 03 Jul 2026 00:00:00 GMT

养老保险缴费年限怎么看#

养老保险常被简化成“交够多少年就行”，但真实生活里还会遇到换城市、换单位、灵活就业、断缴和关系转移。

为什么这件事重要#

缴费年限可以理解为长期权益的累计记录。它不是短期理财产品，也不是单独存在的账户余额，而是和个人参保记录、缴费基数、退休地规则等因素相关。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

普通人应该定期查个人参保记录，尤其是换工作、离职、跨城市工作以后。发现某个月份缺失，要尽早问清是单位申报延迟、系统同步慢，还是确实没有缴。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要只问“公司交没交”，要看正式平台记录。口头说法和系统记录不一致时，以正式记录为准继续核对。

资料来源#

小结#

养老保险缴费年限怎么看的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

滑动窗口处理最长无重复子串

Fri, 03 Jul 2026 00:00:00 GMT

滑动窗口处理最长无重复子串#

滑动窗口适合处理连续区间问题。最长无重复子串的核心，不是枚举所有子串，而是维护一个始终合法的窗口。

算法题真正要练的是把题目翻译成状态、边界和转移。模板可以帮助提速，但不能替代对条件的判断。

题型识别#

当右指针加入新字符后，如果出现重复，就移动左指针直到窗口重新合法。窗口每次合法时，用长度更新答案。

遇到类似题时，我会先写一句话解释输入、输出和约束，再决定用什么结构。只要这一步说不清，直接写代码大概率会在边界条件上出错。

核心写法#

1
def length_of_longest_substring(s):
2
    seen = {}
3
    left = 0
4
    ans = 0
5
    for right, ch in enumerate(s):
6
        if ch in seen and seen[ch] >= left:
7
            left = seen[ch] + 1
8
        seen[ch] = right
9
        ans = max(ans, right - left + 1)
10
    return ans

边界样例#

空输入或只有一个元素时，答案应该是什么。
元素重复时，比较关系是否仍然成立。
结果需要下标、长度、数量，还是具体路径。
时间复杂度能不能从每个元素处理次数解释出来。

复盘#

复盘时要看左指针是否只向右移动。只要每个字符最多进窗口一次、出窗口一次，整体复杂度就是 O(n)。

最小验收样例#

写完后不要只看答案，还要能解释每一步状态为什么变化。只要能把状态变化讲清楚，换一个题面时就不容易机械套错模板。

小结#

滑动窗口处理最长无重复子串的练习重点，是把固定套路拆成可解释的判断。能说明为什么这样维护状态，才算真正掌握。

二分查找边界写法笔记

Thu, 02 Jul 2026 00:00:00 GMT

二分查找边界写法笔记#

二分查找是很基础的算法，但我每隔一段时间还是会在边界上犯错。常见问题包括：left < right 还是 left <= right，right = mid 还是 right = mid - 1，以及循环结束后返回哪个位置。

这篇不追求把所有变体都列出来，只记录两种我自己最常用、也比较容易复用的写法。

1、普通查找：闭区间写法#

如果目标是在有序数组中查找一个确定的值，可以使用闭区间 [left, right]：

1
def binary_search(nums, target):
2
    left, right = 0, len(nums) - 1
3

4
    while left <= right:
5
        mid = (left + right) // 2
6

7
        if nums[mid] == target:
8
            return mid
9
        elif nums[mid] < target:
10
            left = mid + 1
11
        else:
12
            right = mid - 1
13

14
    return -1

这里 right 一开始是最后一个有效下标，所以循环条件是 left <= right。当 left == right 时，区间里还剩一个元素，需要继续检查。

2、为什么要加一减一#

闭区间写法里，mid 已经被检查过了。如果 nums[mid] < target，说明 mid 以及它左边都不可能是答案，所以下一次从 mid + 1 开始。

同理，如果 nums[mid] > target，下一次应该到 mid - 1：

1
left = mid + 1
2
right = mid - 1

如果这里写成 left = mid 或 right = mid，在某些情况下区间不会缩小，就可能出现死循环。

3、查找第一个满足条件的位置#

实际刷题时，更常见的是找边界：比如第一个大于等于 target 的位置。这个时候我更喜欢左闭右开区间 [left, right)：

1
def lower_bound(nums, target):
2
    left, right = 0, len(nums)
3

4
    while left < right:
5
        mid = (left + right) // 2
6

7
        if nums[mid] >= target:
8
            right = mid
9
        else:
10
            left = mid + 1
11

12
    return left

这段代码返回的是第一个满足 nums[i] >= target 的下标。如果所有元素都小于 target，返回值会是 len(nums)。

4、用例子走一遍#

假设：

1
nums = [1, 3, 3, 5, 8]
2
target = 3

我们想找第一个大于等于 3 的位置，也就是下标 1。

初始区间是 [0, 5)，mid = 2，nums[2] = 3，满足条件，所以答案可能是 2，也可能在左边，于是 right = 2。

接着区间变成 [0, 2)，mid = 1，nums[1] = 3，继续满足条件，right = 1。

再然后区间是 [0, 1)，mid = 0，nums[0] = 1，不满足条件，left = 1。

最后 left == right == 1，返回 1。

5、把条件抽象出来#

很多二分题都可以改写成“找第一个满足条件的位置”：

1
def first_true(n, check):
2
    left, right = 0, n
3

4
    while left < right:
5
        mid = (left + right) // 2
6

7
        if check(mid):
8
            right = mid
9
        else:
10
            left = mid + 1
11

12
    return left

只要 check(i) 的结果从 False 到 True 只变化一次，这个模板就能使用。

例如在答案区间里找最小可行值时，check(mid) 就是“当前答案是否可行”。

小结#

我现在会把二分查找分成两类记：

找具体值：闭区间 [left, right]，循环条件 left <= right。
找边界位置：左闭右开 [left, right)，循环条件 left < right。

最重要的是不要混用规则。只要区间定义清楚，mid 是否已经排除、返回 left 还是 -1，都会变得更容易判断。

博客图片 alt 文本整理笔记

Thu, 02 Jul 2026 00:00:00 GMT

博客图片 alt 文本整理笔记#

写博客时，我以前经常只关注图片能不能显示，很少认真写图片的 alt 文本。后来整理旧文章时发现，如果图片加载失败，或者读者使用屏幕阅读器，很多截图就只剩下一个空链接，文章信息会断掉。

所以现在写 Markdown 图片时，我会顺手把 alt 文本补上。它不需要很长，但要能说明图片在文章里的作用。

1、Markdown 图片的基本写法#

Markdown 中插入图片通常是：

1
![图片说明](./images/demo.png)

方括号里的内容就是 alt 文本。它不是给搜索引擎随便堆关键词的地方，而是图片无法正常观看时的替代说明。

如果只是这样写：

1
![](./images/error.png)

图片一旦加载失败，读者就很难知道这里原本想表达什么。

2、不要写成无意义描述#

有些 alt 看起来写了，但实际帮助不大：

1
![图片](./images/chart.png)
2
![截图](./images/terminal.png)
3
![示意图](./images/flow.png)

这些词太泛了。更好的写法是说明图片内容和上下文：

1
![终端中显示 ModuleNotFoundError 的报错位置](./images/import-error.png)
2
![按日期统计订单数量后的柱状图结果](./images/order-chart.png)
3
![前端请求经过 Nginx 转发到后端接口的流程](./images/proxy-flow.png)

读者即使看不到图片，也能大致知道这里展示的是什么。

3、截图类图片写关键结论#

技术博客里经常会放终端截图、网页截图或配置界面截图。写 alt 时不要只写“终端截图”，最好写出截图里最重要的信息。

例如一张构建成功截图，可以写：

1
![pnpm build 执行完成并显示生成静态页面数量](./images/build-success.png)

如果截图是报错信息，可以写：

1
![浏览器控制台显示接口返回 404 的错误信息](./images/api-404.png)

这样后面回看文章时，也能更快理解图片为什么放在这里。

4、流程图类图片写结构关系#

如果图片是流程图，alt 可以简要描述节点关系：

1
![数据从 CSV 读取后经过清洗、分组统计并导出 Excel 的流程](./images/data-flow.png)

不需要把图里的所有文字完整重复一遍，但要把主线讲清楚。

如果流程比较复杂，可以在图片下面再补一段正文说明，而不是把所有信息塞进 alt。

5、整理旧文章时的检查清单#

给旧博客补 alt 时，我会按这几个问题检查：

图片是否有方括号说明。
说明是否比“图片”“截图”更具体。
是否写出了图片和当前段落的关系。
如果图片加载失败，读者能否继续理解文章。
同一篇文章里的图片说明是否风格一致。

可以先用搜索找出空 alt：

Terminal window

1
grep -R \"!\\[\\]\" src/content/posts

如果是在 Windows PowerShell 里，也可以用：

Terminal window

1
Select-String -Path "src/content/posts/**/*.md" -Pattern "!\[\]"

6、我的写法原则#

我现在会把 alt 当成一句短说明，而不是标题。一般控制在一行内，优先写清楚三件事：

1
图片类型 + 关键内容 + 和文章步骤的关系

比如：

1
![Pagefind 构建日志中提示跳过 guestbook 页面](./images/pagefind-warning.png)

这句话说明了图片来自哪里、显示了什么、为什么值得放进文章。

小结#

博客图片 alt 文本不是装饰项。它可以让文章在图片加载失败、读屏阅读、后期维护时都更容易理解。

我的最低要求是：不要空着，不要只写“图片”，尽量写出图片的关键信息和上下文。这个习惯不会增加太多写作成本，但能明显提升文章的可读性和可维护性。

pandas merge 合并表格检查清单

Thu, 02 Jul 2026 00:00:00 GMT

pandas merge 合并表格检查清单#

做数据分析时，经常需要把两张表合在一起。比如一张订单表里只有商品编号，另一张商品表里有商品名称和分类。这个时候就会用到 pandas.merge。

merge 本身不难，真正容易出错的是合并前后的检查。如果键字段有重复、类型不一致，或者合并方式选错，结果可能会多出很多行，也可能悄悄丢掉数据。

这篇记录一份我常用的检查清单。

1、准备两张示例表#

1
import pandas as pd
2

3
orders = pd.DataFrame({
4
    "order_id": [1001, 1002, 1003, 1004],
5
    "product_id": ["P01", "P02", "P02", "P04"],
6
    "count": [2, 1, 3, 1],
7
})
8

9
products = pd.DataFrame({
10
    "product_id": ["P01", "P02", "P03"],
11
    "name": ["键盘", "鼠标", "显示器"],
12
    "category": ["外设", "外设", "屏幕"],
13
})

这里订单表中有一个 P04，商品表里没有对应记录。这个缺口正好可以用来观察不同合并方式的结果。

2、先检查键字段类型#

合并前先看两边的字段类型：

1
print(orders.dtypes)
2
print(products.dtypes)

如果一边是数字，一边是字符串，即使看起来内容一样，也可能合不上。比如 1001 和 "1001" 是不同类型。

可以统一转成字符串：

1
orders["product_id"] = orders["product_id"].astype(str)
2
products["product_id"] = products["product_id"].astype(str)

这一步尤其适合编号、学号、手机号这类字段，因为它们本质上不是用来计算的数字。

3、检查右表键是否重复#

如果商品表里 product_id 重复，合并后订单行数可能会被放大。可以这样检查：

1
dup = products[products["product_id"].duplicated(keep=False)]
2
print(dup)

如果输出不为空，就要先确认重复是否合理。

有些重复代表数据错误，需要去重：

1
products = products.drop_duplicates(subset=["product_id"])

但有些重复代表一对多关系，比如一个用户有多条标签记录，这时不能盲目去重，而要先明确分析目标。

4、选择合并方式#

最常见的是左连接，也就是保留订单表的所有行：

1
merged = orders.merge(products, on="product_id", how="left")
2
print(merged)

如果商品表缺少 P04，合并结果里对应的 name 和 category 会是空值。这样比较适合“以订单为主”的分析。

如果只想保留两边都能匹配上的记录，可以使用内连接：

1
matched = orders.merge(products, on="product_id", how="inner")

内连接会丢掉没有匹配上的订单，所以使用前要确认这是不是你想要的结果。

5、合并后检查行数和缺失值#

合并完成后，不要马上进入统计步骤，先检查行数：

1
print("orders:", len(orders))
2
print("merged:", len(merged))

如果是左连接，并且右表键没有重复，合并前后行数应该一致。

再检查没有匹配上的记录：

1
missing = merged[merged["name"].isna()]
2
print(missing)

这些记录通常需要单独处理。可能是商品表漏了，也可能是订单表里的编号写错了。

6、用 indicator 查看来源#

调试合并问题时，可以加上 indicator=True：

1
check = orders.merge(
2
    products,
3
    on="product_id",
4
    how="outer",
5
    indicator=True,
6
)
7

8
print(check["_merge"].value_counts())

_merge 会告诉我们每一行来自左表、右表，还是两边都匹配上了。这个方法很适合检查数据对齐情况。

小结#

我使用 merge 时一般会按这个顺序做：

先检查键字段类型。
再检查键字段是否重复。
明确使用 left、inner 还是 outer。
合并后检查行数是否符合预期。
用缺失值和 _merge 找出没有匹配上的记录。

表格合并最怕结果“看起来能跑”，但其实行数已经错了。把检查步骤固定下来，比事后从统计结果里倒查问题更省时间。

试用期也要关注社保记录

Thu, 02 Jul 2026 00:00:00 GMT

试用期也要关注社保记录#

很多人以为试用期只是双方互相观察，所以社保可以等转正再说。这个想法很危险，因为社保记录不是情面问题，而是劳动关系和权益连续性的证据。

为什么这件事重要#

试用期仍然处在劳动合同关系中。个人要关注劳动合同起始时间、工资条、社保缴纳月份和公积金缴存状态，这些材料将来可能影响医保、失业、购房贷款或城市公共服务资格。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

最简单的做法是入职后定期在当地社保、公积金平台查记录，确认单位名称、缴费月份、缴费基数是否和工资条大致匹配。发现异常先保存证据，再和 HR 沟通。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要只听口头承诺。转正后补缴、以后统一处理、公司都这样做，这些说法都应该落到正式记录上。

资料来源#

小结#

试用期也要关注社保记录的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

Python 环境复现检查笔记

Thu, 02 Jul 2026 00:00:00 GMT

Python 环境复现检查笔记#

最近把一个小脚本从自己的电脑挪到另一台机器上运行，结果同一份代码在本机正常，在新环境里却连续出现依赖缺失、版本不一致和路径找不到的问题。

这类问题不能只靠“重新装一下包”解决。更稳妥的做法是先把运行环境拆开检查：到底用的是哪个 Python、安装了哪些依赖、从哪个目录启动、需要哪些环境变量。这里把我的排查步骤整理下来。

1、先确认解释器路径#

第一步不要直接看 python --version，因为版本号相同也可能对应不同环境。可以打印解释器的完整路径：

Terminal window

1
python -c "import sys; print(sys.executable)"

如果项目使用虚拟环境，正常情况下路径里应该能看到 .venv、venv 或 conda 环境名。

在 Windows 上还可以顺手看一下命令解析结果：

Terminal window

1
where python

如果输出里有多个 Python 路径，就要确认当前终端实际排在第一位的是哪一个。

2、导出当前可运行环境的依赖#

如果原机器还能正常运行，先在原机器上导出依赖：

Terminal window

1
python -m pip freeze > requirements.txt

然后在新机器上创建环境并安装：

Terminal window

1
python -m venv .venv
2
.\.venv\Scripts\activate
3
python -m pip install -r requirements.txt

这里推荐始终使用 python -m pip，不要直接用 pip。这样可以减少 pip 指向另一个 Python 的情况。

3、记录项目的启动目录#

有些脚本在项目根目录运行正常，换到子目录运行就失败。原因通常是代码里使用了相对路径，例如：

1
from pathlib import Path
2

3
data_path = Path("data/input.csv")

这个路径不是相对于 Python 文件，而是相对于当前命令行所在目录。为了避免误判，可以在启动时打印：

1
from pathlib import Path
2

3
print("cwd:", Path.cwd())

如果项目必须从根目录启动，可以把启动命令写进 README 或脚本里，例如：

Terminal window

1
python scripts/run_report.py

不要只写“运行 run_report.py”，否则下次很容易在错误目录里启动。

4、检查依赖版本是否真的一致#

有些问题不是包缺失，而是版本变了。比如 pandas、numpy、torch、opencv 这类库，版本差异可能影响 API 或运行结果。

可以对关键包单独检查：

Terminal window

1
python -c "import pandas as pd; print(pd.__version__)"
2
python -c "import numpy as np; print(np.__version__)"

如果项目对版本敏感，requirements.txt 里最好保留精确版本：

1
pandas==2.2.2
2
numpy==1.26.4

等项目稳定后，再考虑升级依赖，而不是在复现问题时顺手升级。

5、把环境变量列成清单#

很多项目还依赖环境变量，例如接口地址、数据库路径、模型文件目录等。可以准备一个 .env.example：

1
DATA_DIR=./data
2
OUTPUT_DIR=./outputs
3
API_BASE_URL=http://localhost:8000

真正的 .env 不一定提交到仓库，但示例文件可以告诉别人需要配置哪些项。

如果变量缺失，代码里也应该给出明确错误：

1
import os
2

3
data_dir = os.getenv("DATA_DIR")
4
if not data_dir:
5
    raise RuntimeError("缺少 DATA_DIR 环境变量")

这样比后面出现一个“文件不存在”的报错更容易定位。

小结#

Python 项目换环境运行时，我现在会按这个顺序检查：

先确认 sys.executable，不要只看版本号。
用 python -m pip freeze 固定当前可运行依赖。
明确从哪个目录启动项目。
单独检查关键库版本。
把环境变量写成 .env.example 或清单。

环境复现的关键不是记住某一次安装命令，而是把“能运行的条件”记录完整。以后迁移电脑、部署服务器或交给别人运行时，排查成本会低很多。

单调队列入门实践笔记

Thu, 02 Jul 2026 00:00:00 GMT

单调队列入门实践笔记#

最近复习滑动窗口相关题目时，又遇到了“每个窗口里的最大值”这个问题。最直接的想法是每移动一次窗口，就重新扫描窗口里的所有元素。但如果数组很长、窗口也不小，这种做法会重复比较很多次。

单调队列就是用来减少这种重复工作的。它本质上还是一个队列，只是队列里会维护一个顺序，让队头始终能代表当前窗口里的最优答案。

1、先看暴力解法的问题#

假设数组是：

1
nums = [1, 3, -1, -3, 5, 3, 6, 7]
2
k = 3

每个长度为 3 的窗口最大值依次是：

1
[1, 3, -1] -> 3
2
[3, -1, -3] -> 3
3
[-1, -3, 5] -> 5
4
[-3, 5, 3] -> 5
5
[5, 3, 6] -> 6
6
[3, 6, 7] -> 7

暴力写法很容易理解：

1
def max_sliding_window(nums, k):
2
    ans = []
3
    for i in range(len(nums) - k + 1):
4
        ans.append(max(nums[i:i + k]))
5
    return ans

但这里每个窗口都重新 max 一次。窗口之间明明有大量重叠元素，却没有复用之前的信息。

2、队列里应该保存什么#

单调队列通常保存下标，而不是直接保存数值。原因是我们既要比较大小，也要判断元素是否已经滑出窗口。

比如当前遍历到下标 i，窗口左边界是：

1
left = i - k + 1

如果队头下标小于 left，说明它已经不在窗口里，需要弹出。

3、为什么要保持单调递减#

我们想快速得到窗口最大值，所以队头应该对应当前窗口中最大的数。为了做到这一点，队列里的值可以保持从大到小。

当新元素 nums[i] 进来时，如果队尾对应的值比它小，那么队尾元素以后也不可能成为最大值：

它比新元素小。
它还比新元素更早离开窗口。

所以可以直接从队尾弹掉。

1
while q and nums[q[-1]] <= nums[i]:
2
    q.pop()

这一步是单调队列的核心。

4、完整代码#

用 collections.deque 写起来比较清楚：

1
from collections import deque
2

3
def max_sliding_window(nums, k):
4
    q = deque()
5
    ans = []
6

7
    for i, x in enumerate(nums):
8
        left = i - k + 1
9

10
        while q and q[0] < left:
11
            q.popleft()
12

13
        while q and nums[q[-1]] <= x:
14
            q.pop()
15

16
        q.append(i)
17

18
        if i >= k - 1:
19
            ans.append(nums[q[0]])
20

21
    return ans

展开收起

这里的 q[0] 始终是当前窗口最大值的下标。只有当窗口已经形成，也就是 i >= k - 1 时，才把答案加入列表。

5、用一个窗口走一遍#

还是看这个数组：

1
nums = [1, 3, -1]

遍历到 1 时，队列为空，直接加入下标 0。

遍历到 3 时，队尾的 1 比 3 小，弹出下标 0，再加入下标 1。此时队头就是 3。

遍历到 -1 时，队尾的 3 比 -1 大，不弹出，加入下标 2。窗口形成后，队头仍然是下标 1，对应最大值 3。

这个过程说明，队列里不需要保存窗口内所有元素，只保留“未来可能成为最大值”的候选下标。

6、常见边界检查#

写单调队列时，我会特别检查这几个地方：

队列保存的是下标，不是值。
先移除滑出窗口的队头。
再从队尾移除不可能成为答案的元素。
窗口长度达到 k 后再记录答案。
比较时使用 < 还是 <= 要保持一致。

在滑动窗口最大值里，我通常写 nums[q[-1]] <= x，这样相同值时保留更新的下标，过期判断会更自然。

小结#

单调队列可以理解为“带淘汰规则的候选答案队列”。它不是为了保存所有窗口元素，而是为了让队头随时代表当前窗口的最大值。

对我来说，掌握这个结构的关键是两句话：过期的下标从队头走掉，更弱的候选从队尾删掉。只要这两步写清楚，滑动窗口最大值这类题就会稳定很多。

YOLO11 标签文件检查清单

Thu, 02 Jul 2026 00:00:00 GMT

YOLO11 标签文件检查清单#

训练 YOLO11 时，如果数据集目录已经整理好了，下一步最容易忽略的就是标签文件。标签看起来只是一些 txt 文件，但只要类别编号错了、坐标超出范围、图片和标签没有对应上，训练结果就会很差。

这篇记录一份训练前的标签检查清单，重点放在能快速发现问题的几个地方。

1、确认图片和标签一一对应#

YOLO 数据集一般会有这样的结构：

1
dataset/
2
  images/
3
    train/
4
      001.jpg
5
      002.jpg
6
  labels/
7
    train/
8
      001.txt
9
      002.txt

图片名和标签名需要一一对应，只是扩展名不同。可以用 Python 做一个简单检查：

1
from pathlib import Path
2

3
image_dir = Path("dataset/images/train")
4
label_dir = Path("dataset/labels/train")
5

6
images = {p.stem for p in image_dir.glob("*") if p.suffix.lower() in [".jpg", ".png", ".jpeg"]}
7
labels = {p.stem for p in label_dir.glob("*.txt")}
8

9
print("缺少标签的图片:", sorted(images - labels)[:20])
10
print("没有图片的标签:", sorted(labels - images)[:20])

如果输出不为空，就要先修正文件名或移动路径。

2、检查每一行的字段数量#

YOLO 检测标签每一行通常是：

1
class_id x_center y_center width height

也就是 5 个字段。可以扫描所有标签文件：

1
from pathlib import Path
2

3
for txt in Path("dataset/labels/train").glob("*.txt"):
4
    for i, line in enumerate(txt.read_text().splitlines(), start=1):
5
        if not line.strip():
6
            continue
7
        parts = line.split()
8
        if len(parts) != 5:
9
            print("字段数量异常:", txt, "line", i, line)

有时候标注工具导出的文件里会有空格、空行或额外字段，训练前最好先发现。

3、检查类别编号范围#

如果 data.yaml 中写了 3 个类别：

1
names:
2
  0: person
3
  1: helmet
4
  2: vest

那么标签里的类别编号只能是 0、1、2。可以这样检查：

1
num_classes = 3
2

3
for txt in Path("dataset/labels/train").glob("*.txt"):
4
    for i, line in enumerate(txt.read_text().splitlines(), start=1):
5
        if not line.strip():
6
            continue
7
        class_id = int(float(line.split()[0]))
8
        if class_id < 0 or class_id >= num_classes:
9
            print("类别编号越界:", txt, "line", i, class_id)

类别编号越界会直接影响训练，尤其是从多个数据集拼接时，很容易忘记重新映射类别。

4、检查坐标是否在 0 到 1 之间#

YOLO 标签中的坐标是归一化后的值，理论上都应该在 0 到 1 之间：

1
for txt in Path("dataset/labels/train").glob("*.txt"):
2
    for i, line in enumerate(txt.read_text().splitlines(), start=1):
3
        if not line.strip():
4
            continue
5
        values = [float(x) for x in line.split()[1:]]
6
        if any(v < 0 or v > 1 for v in values):
7
            print("坐标越界:", txt, "line", i, values)

如果发现大量坐标大于 1，可能是导出的不是 YOLO 格式，而是像素坐标格式。

5、抽样可视化标签#

脚本检查只能发现格式问题，不能判断框的位置是否真的正确。训练前最好抽几张图画出来看：

1
import cv2
2
from pathlib import Path
3

4
img_path = Path("dataset/images/train/001.jpg")
5
txt_path = Path("dataset/labels/train/001.txt")
6

7
img = cv2.imread(str(img_path))
8
h, w = img.shape[:2]
9

10
for line in txt_path.read_text().splitlines():
11
    cls, x, y, bw, bh = map(float, line.split())
12
    x1 = int((x - bw / 2) * w)
13
    y1 = int((y - bh / 2) * h)
14
    x2 = int((x + bw / 2) * w)
15
    y2 = int((y + bh / 2) * h)
16
    cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
17

18
cv2.imwrite("label_check.jpg", img)

展开收起

打开 label_check.jpg 看一下框是否贴合目标。这个步骤很简单，但能避免很多后续训练时间浪费。

小结#

训练 YOLO11 前，我会至少检查这几项：

图片和标签是否一一对应。
每行标签是否正好 5 个字段。
类别编号是否在 data.yaml 范围内。
坐标是否都在 0 到 1 之间。
随机抽样可视化标注框。

模型效果不好时，不一定是模型结构或参数的问题。很多时候，先把标签质量检查清楚，比盲目调学习率更有效。

博客文章 Frontmatter 模板整理

Wed, 01 Jul 2026 00:00:00 GMT

博客文章 Frontmatter 模板整理#

今天写博客时发现一个小问题：文章正文写完了，但是发布前还要回头检查标题、日期、分类、标签、草稿状态。字段不多，但如果每次都手写，还是容易漏掉。

所以这里整理一个自己常用的 frontmatter 模板，之后新建文章时可以直接复制再修改。

1、最基础的模板#

一篇普通公开文章，可以先写成这样：

1
---
2
title: "文章标题"
3
published: 2026-07-01
4
description: "一句话说明这篇文章解决什么问题。"
5
image: "api"
6
tags: ["标签1", "标签2"]
7
category: "分类名称"
8
draft: false
9
comment: true
10
---

我觉得最关键的是 published、category、draft 这三个字段。日期决定归档位置，分类决定读者从哪里找到文章，draft: false 决定文章是否公开显示。

2、标题和描述先写朴素一点#

标题不一定要很花哨，学习博客更重要的是让自己以后能搜索到。例如：

1
Python 路径问题排查
2
pandas 缺失值处理
3
BFS 广度优先搜索模板

这些标题都很直接，过几个月回头找也能知道文章内容。description 可以写成一句问题说明：

1
记录 pandas 中缺失值检查、删除、填充和统计的常用写法。

这样首页和搜索页展示时也比较清楚。

3、分类不要随便新增#

分类最好保持稳定。比如我现在常用的分类有：

1
问题解决
2
博客相关分类
3
计算机视觉
4
数据分析
5
数据结构与算法

如果每篇文章都随手创建一个新分类，后面分类页会变得很乱。更好的做法是：先判断文章属于哪条学习线，再放进已有分类。

4、标签写得比分类细一点#

分类是大方向，标签可以更具体。例如一篇 pandas 文章：

1
tags: ["数据分析", "pandas", "缺失值"]
2
category: "数据分析"

这样以后既可以按“数据分析”看一组文章，也可以按“pandas”找到同一个工具相关的笔记。

5、发布前检查清单#

每次发布前，我会简单看一下：

1
1. published 是否是今天或正确发布日期
2
2. category 是否属于已有分类
3
3. tags 是否和正文主题一致
4
4. draft 是否为 false
5
5. comment 是否按需要开启
6
6. 正文第一段是否说明了问题背景

这个检查不复杂，但能减少很多发布后的修改。

总结#

frontmatter 是博客文章的元信息。它不属于正文内容，但会影响文章是否展示、如何归档、进入哪个分类。把模板固定下来，可以让写文章更像一个稳定流程，而不是每次都临时想字段怎么填。

DFS 回溯模板整理

Wed, 01 Jul 2026 00:00:00 GMT

DFS 回溯模板整理#

学习搜索算法时，DFS 和回溯经常放在一起出现。刚开始容易混乱：递归什么时候结束，路径什么时候加入答案，为什么递归回来还要撤销选择。

今天用全排列问题整理一个基础模板。

1、问题描述#

给定一个数组：

1
[1, 2, 3]

要求输出所有排列：

1
[1, 2, 3]
2
[1, 3, 2]
3
[2, 1, 3]
4
[2, 3, 1]
5
[3, 1, 2]
6
[3, 2, 1]

这个问题适合用 DFS 回溯，因为每一层都在选择一个还没使用过的数字。

2、先写出三个核心变量#

回溯里我习惯先想三个东西：

1
path：当前已经选择的路径
2
used：某个数字是否已经用过
3
ans：保存最终答案

然后每次递归都做一件事：从还没用过的数字里选一个，放进 path。

3、Python 模板#

1
def permute(nums):
2
    ans = []
3
    path = []
4
    used = [False] * len(nums)
5

6
    def dfs():
7
        if len(path) == len(nums):
8
            ans.append(path.copy())
9
            return
10

11
        for i in range(len(nums)):
12
            if used[i]:
13
                continue
14

15
            path.append(nums[i])
16
            used[i] = True
17

18
            dfs()
19

20
            used[i] = False
21
            path.pop()
22

23
    dfs()
24
    return ans
25

26
print(permute([1, 2, 3]))

展开收起

这里最重要的是递归后的两行：

1
used[i] = False
2
path.pop()

它们表示撤销当前选择，回到进入这一层之前的状态，然后继续尝试下一个数字。

4、为什么要 path.copy()#

保存答案时不能直接写：

1
ans.append(path)

因为 path 是一个会继续变化的列表。后面不断 append 和 pop，答案里的引用也会跟着变。应该保存当前路径的副本：

1
ans.append(path.copy())

这是回溯题里很常见的小坑。

5、套模板时先问三个问题#

以后遇到类似题目，可以先问：

1
1. 递归终止条件是什么？
2
2. 每一层有哪些选择？
3
3. 做出选择后，递归回来要撤销什么？

比如组合问题、子集问题、棋盘搜索问题，都可以从这三个问题开始拆。

总结#

DFS 回溯的写法可以概括成：选择、递归、撤销选择。全排列是最基础的例子，能看清楚 path、used 和 ans 的作用。模板背下来不是目的，关键是理解每一层递归都在枚举当前可选项。

五险一金到底包含什么

Wed, 01 Jul 2026 00:00:00 GMT

五险一金到底包含什么#

刚工作时最容易把“五险一金”“社保”“公积金”混成一个词。其实它们不是同一层概念，理解清楚以后，才能看懂工资条和入职材料。

为什么这件事重要#

“五险”通常指养老、医疗、失业、工伤、生育五类社会保险；“一金”指住房公积金。社保主要对应五类社会保险，五险一金比社保多了住房公积金。

很多人不是不努力，而是第一次遇到这些规则时没有人把边界讲清楚。先知道它影响什么，再决定要不要继续深入查细则。

普通人要核对什么#

普通人最该关注的是缴费基数、个人缴费部分、单位缴费部分和权益用途。工资条上扣的钱只是个人部分，单位还会另外承担一部分成本。

一张自查清单#

它影响的是当月现金流、长期保障、住房资格，还是投资风险。
记录能否在官方平台、合同或产品文件中查到。
个人承担什么成本，单位、平台或市场承担什么责任。
出现争议时，应该先找单位、人社/公积金经办机构、销售机构，还是监管渠道。

容易误解的地方#

不要把五险一金理解成“公司福利”。它更接近劳动关系下的制度性安排，是否缴、怎么缴、何时能用，都要看当地规则和正式记录。

资料来源#

小结#

五险一金到底包含什么的重点是建立基本判断力。先理解制度和风险边界，再谈选择，才能避免被碎片化说法带着走。

pandas groupby 分组统计笔记

Wed, 01 Jul 2026 00:00:00 GMT

pandas groupby 分组统计笔记#

做表格分析时，经常会遇到一个问题：原始数据是一行一条记录，但我们真正想看的结果是按类别汇总后的统计值。比如按商品类别统计销售额，按班级统计平均分，按日期统计订单数量。

在 pandas 里，这类问题一般用 groupby 解决。

1、准备一份示例数据#

1
import pandas as pd
2

3
data = {
4
    "日期": ["2026-07-01", "2026-07-01", "2026-07-02", "2026-07-02"],
5
    "类别": ["图书", "数码", "图书", "数码"],
6
    "销量": [3, 2, 5, 1],
7
    "单价": [40, 300, 35, 280],
8
}
9

10
df = pd.DataFrame(data)
11
df["销售额"] = df["销量"] * df["单价"]
12
print(df)

这里先增加一列 销售额，后面统计时会用到。

2、按一个字段分组#

如果想看每个类别的总销售额：

1
result = df.groupby("类别")["销售额"].sum()
2
print(result)

输出结果的索引就是类别，值就是每个类别汇总后的销售额。

如果希望结果仍然是普通表格，可以加上：

1
result = df.groupby("类别", as_index=False)["销售额"].sum()
2
print(result)

as_index=False 对后续导出 Excel 或继续合并数据比较方便。

3、按多个字段分组#

如果想看每天、每个类别的销售额：

1
result = df.groupby(["日期", "类别"], as_index=False)["销售额"].sum()
2
print(result)

多个字段分组时，可以理解为先按日期分，再在每个日期里面按类别分。

4、一次统计多个指标#

实际分析时，经常不只看一个指标。可以使用 agg：

1
summary = df.groupby("类别", as_index=False).agg(
2
    总销量=("销量", "sum"),
3
    平均单价=("单价", "mean"),
4
    总销售额=("销售额", "sum"),
5
)
6
print(summary)

这种写法的好处是输出列名可以自己命名，结果比较清楚。

5、排序和筛选#

汇总后通常还要排序：

1
summary = summary.sort_values("总销售额", ascending=False)
2
print(summary)

也可以筛选出销售额较高的类别：

1
high = summary[summary["总销售额"] > 200]
2
print(high)

这样就能从原始明细数据得到更适合观察的统计结果。

总结#

groupby 的核心思路是“先分组，再统计”。单字段分组适合看某个类别的汇总，多字段分组适合看交叉维度，agg 适合一次输出多个指标。写分析代码时，可以先把问题翻译成“按什么分组、统计什么列、使用什么函数”，再去写 pandas 代码。

Python import 报错排查清单

Wed, 01 Jul 2026 00:00:00 GMT

Python import 报错排查清单#

今天运行一个 Python 脚本时，又遇到了 ModuleNotFoundError。这个错误看起来很简单，就是找不到包，但是实际原因可能有很多：可能是包没有安装，也可能是装到了另一个环境里，还可能是当前目录和模块名发生了冲突。

这里把排查顺序记录下来，之后再遇到类似问题可以按清单一步一步看。

1、先确认正在使用哪个 Python#

不要只看编辑器左下角显示的解释器，最好直接在终端里打印：

Terminal window

1
python -c "import sys; print(sys.executable)"

如果使用的是 conda 环境，也可以看：

Terminal window

1
conda info --envs

当前环境前面会有一个 *。很多导入失败的问题，本质上就是在 A 环境安装了包，却用 B 环境运行代码。

2、确认包是否安装在当前环境#

以 pandas 为例，可以这样检查：

Terminal window

1
python -m pip show pandas

如果没有输出，说明当前 Python 环境里没有安装这个包。安装时也尽量使用：

Terminal window

1
python -m pip install pandas

这样可以保证 pip 和 python 指向同一个环境，减少装错位置的问题。

3、检查文件名有没有冲突#

有时候我们会把自己的文件命名为：

1
pandas.py
2
torch.py
3
cv2.py

这样 Python 导入时会优先找到当前目录下的同名文件，导致真正的第三方库无法被导入。可以先检查当前目录：

Terminal window

1
dir

如果发现文件名和库名一样，建议改成更具体的名字，例如：

1
pandas_practice.py
2
torch_train_demo.py
3
image_read_test.py

改名后还要删除可能生成的缓存目录：

Terminal window

1
rmdir /s /q __pycache__

Linux 或 macOS 下可以用：

Terminal window

1
rm -rf __pycache__

4、确认项目内部模块路径#

如果导入的是自己写的模块，例如：

1
from utils.file_helper import read_data

需要确认运行命令是在项目根目录执行的。可以打印当前工作目录：

1
from pathlib import Path
2

3
print(Path.cwd())

如果工作目录不对，可以切换到项目根目录后再运行：

Terminal window

1
cd 项目目录
2
python main.py

也可以把项目整理成更清晰的结构：

1
project/
2
  main.py
3
  utils/
4
    __init__.py
5
    file_helper.py

其中 __init__.py 可以让目录更明确地被当作 Python 包来使用。

5、记录一条最小验证命令#

排查结束后，我习惯保留一条最小验证命令：

Terminal window

1
python -c "import pandas as pd; print(pd.__version__)"

如果这条命令可以运行，再去跑完整项目。这样可以把“环境问题”和“业务代码问题”分开判断。

总结#

ModuleNotFoundError 不要只盯着安装命令看。我的排查顺序是：先确认 Python 路径，再确认包是否装在当前环境，然后检查文件名冲突，最后看项目内部模块路径。按这个顺序查，基本能定位大多数导入失败问题。

YOLO11 数据集目录检查

Wed, 01 Jul 2026 00:00:00 GMT

YOLO11 数据集目录检查#

准备训练 YOLO11 时，最容易卡住的地方不是模型代码，而是数据集路径。图片放错位置、标签文件名对不上、data.yaml 写错目录，都会导致训练时找不到数据。

今天记录一套训练前的检查步骤，先把目录确认清楚，再开始跑模型。

1、推荐的数据集结构#

一个常见的检测数据集可以整理成这样：

1
datasets/
2
  my_yolo_data/
3
    images/
4
      train/
5
      val/
6
    labels/
7
      train/
8
      val/
9
    data.yaml

其中 images/train 放训练图片，labels/train 放训练标签；images/val 放验证图片，labels/val 放验证标签。

2、检查图片和标签是否同名#

YOLO 标签文件需要和图片文件同名，只是后缀不同。例如：

1
images/train/0001.jpg
2
labels/train/0001.txt

如果图片是 0001.jpg，标签却写成 1.txt，训练时就会认为这张图片没有标注。

可以用 Python 简单检查：

1
from pathlib import Path
2

3
img_dir = Path("datasets/my_yolo_data/images/train")
4
label_dir = Path("datasets/my_yolo_data/labels/train")
5

6
imgs = {p.stem for p in img_dir.glob("*.*")}
7
labels = {p.stem for p in label_dir.glob("*.txt")}
8

9
print("只有图片没有标签：", sorted(imgs - labels)[:10])
10
print("只有标签没有图片：", sorted(labels - imgs)[:10])

如果两个输出都是空列表，说明文件名基本对应。

3、检查 data.yaml#

data.yaml 可以先写成这样：

1
path: datasets/my_yolo_data
2
train: images/train
3
val: images/val
4

5
names:
6
  0: person
7
  1: car

这里要注意 path 和 train、val 的组合路径是否真的存在。可以手动拼一下：

1
datasets/my_yolo_data/images/train
2
datasets/my_yolo_data/images/val

如果项目在 Windows 上，路径也尽量使用 /，这样复制到命令里更稳定。

4、先跑一个小命令验证#

正式训练前，可以先用较小参数跑一轮：

Terminal window

1
yolo detect train data=datasets/my_yolo_data/data.yaml model=yolo11n.pt epochs=1 imgsz=640 batch=2

这一步不是为了训练效果，而是为了确认数据能被正常读取。只要能进入训练流程，就说明目录、标签和配置大体没问题。

5、常见错误记录#

我目前遇到比较多的是这几类：

1
1. data.yaml 的 path 写成了不存在的相对路径
2
2. images 和 labels 目录层级不一致
3
3. 标签 txt 文件为空或类别编号超过 names 范围
4
4. 图片后缀混用，但检查脚本只匹配了 jpg
5
5. 命令行运行目录不是项目根目录

遇到报错时，可以先从这几个点反查。

总结#

YOLO11 训练前先不要急着调参数。把数据集目录、图片标签对应关系和 data.yaml 检查清楚，比直接跑训练更节省时间。数据能稳定读进去，后面的模型效果才有讨论意义。

服务端口占用排查

Tue, 30 Jun 2026 00:00:00 GMT

服务端口占用排查#

服务启动时报端口占用，说明指定端口已经有进程在监听。处理时先找出是谁占用了端口，再决定停止它还是换端口。

不要直接杀进程，先确认它是不是正在提供线上服务。

Linux 查看端口#

Terminal window

1
ss -lntp | grep ':3000'
2
lsof -i :3000

ss 能看到监听状态和进程信息。没有权限时可能需要 sudo。

Windows 查看端口#

Terminal window

1
netstat -ano | findstr :3000
2
Get-Process -Id <PID>

释放端口#

如果确认占用进程可以停止，优先使用服务自己的停止命令或 systemctl stop。只有临时开发进程才考虑直接 kill。

Terminal window

1
kill -TERM <pid>
2
ss -lntp | grep ':3000' || echo 'port free'

改端口时同步配置#

如果选择改端口，要同步修改前端 API 地址、反向代理、环境变量和防火墙规则。只改启动命令，很可能导致服务启动了但访问不到。

实战复盘#

使用《服务端口占用排查》时，我会先确认环境边界：本地还是服务器，Windows 还是 Linux，开发环境还是线上环境。很多命令本身没错，但换了系统或权限就会得到完全不同的结果。

修复后不要只看报错消失，还要做业务层验证。比如端口释放后服务是否重新启动，缓存清理后页面是否显示新内容，pip 安装后目标环境是否真的能 import。

排查记录的质量取决于可复现性。只要别人能按文章从现象走到验证，这篇文章就不是临时笔记，而是一张可靠的操作卡片。

最小验收样例#

验收《服务端口占用排查》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

端口冲突要先定位进程，再决定停止还是换端口。线上环境尤其要避免误杀正在工作的服务。

Markdown 代码块未闭合排查

Mon, 29 Jun 2026 00:00:00 GMT

Markdown 代码块未闭合排查#

Markdown 代码块少一个反引号，后面的整篇文章都可能变成代码样式。构建不一定失败，但页面阅读体验会明显坏掉。

技术博客里代码块很多，所以发布前检查代码围栏非常必要。

代码块基本写法#

1
```python
2
print("hello")
3
```

开头和结尾都要是三个反引号。开头可以带语言名，结尾不要带。

如何定位未闭合#

如果页面某一段之后全部变成等宽字体，通常就是前面某个代码块没有关闭。先从异常位置往上找最近的 ```。

Terminal window

1
rg -n "```" src/content/posts

批量检查思路#

可以写脚本统计每篇 Markdown 中反引号围栏数量。数量为奇数时，大概率存在未闭合代码块。

1
from pathlib import Path
2

3
for p in Path("src/content/posts").rglob("*.md"):
4
    count = p.read_text(encoding="utf-8").count("```")
5
    if count % 2:
6
        print("odd fences", p, count)

容易混淆的情况#

代码块内部展示 Markdown 代码块，需要换用四个反引号包裹。
中文输入法把反引号打成其他符号。
复制代码时只复制了开头，没有复制结尾。

实战复盘#

把《Markdown 代码块未闭合排查》写成可复用排查记录时，我会保留四类证据：原始现象、执行命令、关键输出、修复后的验证结果。少了其中任何一类，下次遇到类似问题都容易重新猜一遍。

排查类文章不要只写最终命令，还要写为什么先查这里。比如端口问题先看监听进程，Nginx 问题先分清 404 和 403，Python 环境问题先确认解释器路径。

如果修复动作有风险，例如杀进程、删文件、改服务配置，就应该写清回退方式。能恢复，才敢在服务器上操作。

最小验收样例#

验收《Markdown 代码块未闭合排查》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

Markdown 代码块错误通常很小，但影响很大。发布前做一次围栏数量检查，可以避免整页格式错乱。

BFS 广度优先搜索模板

Mon, 29 Jun 2026 00:00:00 GMT

BFS 广度优先搜索模板#

BFS 的全称是 Breadth First Search，也就是广度优先搜索。它最常用的场景是求“最短步数”，比如迷宫从起点走到终点最少需要几步。

BFS 的核心思想可以理解为一圈一圈往外扩展。先处理距离起点为 0 的点，再处理距离为 1 的点，再处理距离为 2 的点，所以第一次到达某个点时，距离一定是最短的。

1、BFS 的基本步骤#

1
1. 创建队列
2
2. 起点入队，并标记已经访问
3
3. 队列不空时，取出队头
4
4. 枚举它能走到的下一个点
5
5. 如果下一个点合法且没有访问过，就更新距离并入队

关键点：

BFS 一般用队列。
每个点通常只入队一次。
dist 数组可以记录到每个点的最短距离。

2、一维图上的 BFS 模板#

1
queue<int> q;
2
q.push(start);
3
dist[start] = 0;
4

5
while (!q.empty()) {
6
    int t = q.front();
7
    q.pop();
8

9
    for (int i = h[t]; i != -1; i = ne[i]) {
10
        int j = e[i];
11
        if (dist[j] == -1) {
12
            dist[j] = dist[t] + 1;
13
            q.push(j);
14
        }
15
    }
16
}

展开收起

这里 dist[j] == -1 表示节点 j 没有被访问过。

3、迷宫最短路模板#

题目场景：

0 表示可以走。
1 表示障碍物。
从左上角走到右下角。
每次只能上下左右移动一格。

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 110;
5

6
int n, m;
7
int g[N][N];
8
int dista[N][N];
9
pair<int, int> q[N * N];
10

11
int bfs() {
12
    memset(dista, -1, sizeof dista);
13

14
    int hh = 0, tt = 0;
15
    q[0] = {0, 0};
16
    dista[0][0] = 0;
17

18
    int dx[4] = {-1, 0, 1, 0};
19
    int dy[4] = {0, 1, 0, -1};
20

21
    while (hh <= tt) {
22
        auto t = q[hh++];
23

24
        for (int i = 0; i < 4; i++) {
25
            int x = t.first + dx[i];
26
            int y = t.second + dy[i];
27

28
            if (x >= 0 && x < n && y >= 0 && y < m
29
                && g[x][y] == 0 && dista[x][y] == -1) {
30
                dista[x][y] = dista[t.first][t.second] + 1;
31
                q[++tt] = {x, y};
32
            }
33
        }
34
    }
35

36
    return dista[n - 1][m - 1];
37
}
38

39
int main() {
40
    cin >> n >> m;
41
    for (int i = 0; i < n; i++) {
42
        for (int j = 0; j < m; j++) {
43
            cin >> g[i][j];
44
        }
45
    }
46

47
    cout << bfs() << endl;
48
    return 0;
49
}

展开收起

4、为什么 BFS 能求最短路#

因为 BFS 是按照距离从小到大的顺序扩展的。

比如起点距离是 0，下一层距离是 1，再下一层距离是 2。某个点第一次被访问时，一定是从最短的路径过来的。如果后面还有其他路径到它，那些路径只会更长或者一样长。

5、容易写错的地方#

（1）忘记初始化距离数组#

1
memset(dista, -1, sizeof dista);

如果不初始化，就无法判断一个点是否访问过。

（2）没有标记起点#

1
dista[0][0] = 0;

起点必须先标记，否则可能重复入队。

（3）坐标边界写错#

1
x >= 0 && x < n && y >= 0 && y < m

二维数组题最容易错的就是边界。

总结#

BFS 模板一定要记住两个东西：

1
队列 q + 距离数组 dist

只要题目问“最少几步”“最短操作次数”“最少转换次数”，第一反应就可以先想 BFS。

博客日常维护清单

Mon, 29 Jun 2026 00:00:00 GMT

博客日常维护清单#

今天把旧博客迁移到新博客之后，我发现博客不是只要能打开就算完成，后面还需要有一套固定的检查流程。否则文章多了以后，很容易出现某一篇没有发布、分类不对、时间被改掉、构建失败等问题。

所以这里整理一份我以后每天可以照着做的博客维护清单。

1、检查文章文件是否写到正确目录#

现在新博客文章都放在：

Terminal window

1
/www/wwwroot/blog_app/blog_web_app/src/content/posts

如果是每天新增的文章，可以统一放在：

Terminal window

1
src/content/posts/daily/年份-月份-日期/

例如今天的文章目录：

Terminal window

1
src/content/posts/daily/2026-06-29/

这样做的好处是：

后面找当天写过什么文章比较方便。
不会和迁移过来的旧文章混在一起。
自动化任务也更容易判断今天是否已经写过。

2、检查 frontmatter 是否完整#

每篇文章开头都需要有这些字段：

1
---
2
title: "文章标题"
3
published: 2026-06-29
4
description: "文章摘要"
5
image: "api"
6
tags: ["博客标签"]
7
category: "博客相关分类"
8
draft: false
9
comment: true
10
---

其中最重要的是：

title：文章标题。
published：发布时间，不要乱改旧文章的发布时间。
category：必须和已有分类一致。
draft: false：表示公开发布。

如果 draft 写成 true，文章就不会出现在前台。

3、检查构建是否成功#

文章写完以后，进入项目目录执行：

Terminal window

1
cd /www/wwwroot/blog_app/blog_web_app
2
NODE_OPTIONS=--max-old-space-size=1536 pnpm build

如果构建成功，会看到类似：

Terminal window

1
[build] Complete!

如果构建失败，通常先检查这几类问题：

frontmatter 的冒号、引号、数组格式是不是写错。
Markdown 代码块是不是少了结尾的三个反引号。
图片地址是不是空字符串以外的非法值。
MDX 文件里是否写了不合法的 JSX。

4、检查公开文章数量#

构建后可以看这个文件：

Terminal window

1
dist/api/allPostMeta.json

里面会列出当前公开文章。如果新增文章没有出现在这里，说明可能是：

draft 还是 true。
分类或日期格式错误导致内容集合校验失败。
文件没有放到 src/content/posts 下面。

5、检查线上页面是否能访问#

构建成功后，需要抽查新文章页面是否返回 200：

Terminal window

1
curl -k -I https://blog.tjcheng.cn/posts/daily/2026-06-29/blog-maintenance-checklist/

如果返回 200 OK，说明页面已经生成并且 Nginx 可以访问。

总结#

博客后续要长期写下去，最重要的是形成固定流程：

1
写文章 -> 检查 frontmatter -> 构建 -> 检查文章元数据 -> 抽查线上页面

只要每天都按这个流程走，后面文章数量变多也不会乱。

pandas 缺失值处理

Mon, 29 Jun 2026 00:00:00 GMT

pandas 缺失值处理#

在做数据分析时，缺失值是非常常见的问题。比如表格中某些学生没有填写成绩，某些商品没有价格，某些用户没有年龄，这些空值如果不处理，后面的统计结果就可能不准确。

今天记录一下 pandas 中缺失值的常用处理方式。

1、构造一份示例数据#

1
import pandas as pd
2
import numpy as np
3

4
data = {
5
    "姓名": ["张三", "李四", "王五", "赵六"],
6
    "数学": [85, np.nan, 90, 76],
7
    "英语": [88, 92, np.nan, 80],
8
    "城市": ["西安", "北京", None, "成都"]
9
}
10

11
df = pd.DataFrame(data)
12
print(df)

这里的 np.nan 和 None 都可以表示缺失值。

2、检查缺失值#

查看每个位置是不是缺失值：

1
print(df.isna())

统计每一列缺失值数量：

1
print(df.isna().sum())

如果只想看哪些列存在缺失值：

1
print(df.isna().any())

这一步一般放在数据分析最开始，用来判断数据质量。

3、删除缺失值#

删除包含缺失值的行：

1
df_drop_row = df.dropna()
2
print(df_drop_row)

删除包含缺失值的列：

1
df_drop_col = df.dropna(axis=1)
2
print(df_drop_col)

注意：删除数据虽然简单，但是可能会损失很多信息。如果数据量本来就不大，要谨慎使用。

4、填充缺失值#

用固定值填充：

1
df_fill = df.fillna(0)
2
print(df_fill)

对不同列使用不同填充值：

1
df_fill = df.fillna({
2
    "数学": df["数学"].mean(),
3
    "英语": df["英语"].mean(),
4
    "城市": "未知"
5
})
6
print(df_fill)

这里数学和英语用平均分填充，城市用“未知”填充。

5、前向填充和后向填充#

有些数据是时间序列，比如每天的温度、价格，可以使用前一个有效值填充：

1
df_forward = df.ffill()
2
print(df_forward)

也可以使用后一个有效值填充：

1
df_backward = df.bfill()
2
print(df_backward)

这种方式适合连续性比较强的数据，不适合随便填所有表格。

6、一个完整的小案例#

1
import pandas as pd
2
import numpy as np
3

4
data = {
5
    "姓名": ["张三", "李四", "王五", "赵六"],
6
    "数学": [85, np.nan, 90, 76],
7
    "英语": [88, 92, np.nan, 80]
8
}
9

10
df = pd.DataFrame(data)
11

12
# 查看缺失情况
13
print(df.isna().sum())
14

15
# 用每列平均值填充分数
16
score_cols = ["数学", "英语"]
17
df[score_cols] = df[score_cols].fillna(df[score_cols].mean())
18

19
# 计算总分和平均分
20
df["总分"] = df[score_cols].sum(axis=1)
21
df["平均分"] = df[score_cols].mean(axis=1)
22

23
print(df)

展开收起

总结#

缺失值处理没有固定答案，一般按照下面的思路来：

1
先检查缺失情况 -> 判断缺失原因 -> 决定删除还是填充 -> 再做统计分析

如果是学习阶段，先掌握 isna()、dropna()、fillna() 这几个方法，基本就能处理大部分简单表格了。

Python 路径问题排查

Mon, 29 Jun 2026 00:00:00 GMT

Python 路径问题排查#

在使用 Python 写脚本时，经常会遇到这种问题：文件明明存在，但是程序一直提示找不到。很多时候不是文件真的不存在，而是当前运行目录和我们想的不一样。

今天记录一下 Python 路径问题的排查方法。

1、先看当前工作目录#

Python 读取相对路径时，是从“当前工作目录”开始找，不一定是从 .py 文件所在目录开始找。

可以先打印：

1
import os
2

3
print(os.getcwd())

如果输出目录不是你以为的项目目录，那么相对路径就容易错。

例如：

1
open("data/test.txt", "r", encoding="utf-8")

这行代码实际寻找的是：

1
当前工作目录/data/test.txt

2、检查文件是否真的存在#

1
from pathlib import Path
2

3
p = Path("data/test.txt")
4
print(p.exists())
5
print(p.resolve())

exists() 可以判断文件是否存在，resolve() 可以打印绝对路径。这样就能看清楚 Python 到底在找哪个文件。

3、使用脚本所在目录作为基准#

如果希望无论从哪里运行脚本，都能找到同目录下的文件，可以这样写：

1
from pathlib import Path
2

3
BASE_DIR = Path(__file__).resolve().parent
4
file_path = BASE_DIR / "data" / "test.txt"
5

6
print(file_path)
7
print(file_path.exists())
8

9
content = file_path.read_text(encoding="utf-8")
10
print(content)

这样路径就和脚本文件位置绑定，不受命令行当前目录影响。

4、不要手动拼接斜杠#

不推荐这样写：

1
path = "data" + "/" + "test.txt"

更推荐：

1
from pathlib import Path
2

3
path = Path("data") / "test.txt"

pathlib 会自动处理不同系统下的路径分隔符。

5、Windows 路径注意反斜杠#

Windows 路径中经常有反斜杠：

1
path = "C:\new\test.txt"

这里 \n 会被当成换行，所以可能出错。可以写成原始字符串：

1
path = r"C:\new\test.txt"

或者使用双反斜杠：

1
path = "C:\\new\\test.txt"

更推荐使用 Path：

1
from pathlib import Path
2

3
path = Path("C:/new/test.txt")

6、一个完整排查模板#

1
from pathlib import Path
2
import os
3

4
print("当前工作目录：", os.getcwd())
5
print("脚本文件路径：", Path(__file__).resolve())
6

7
BASE_DIR = Path(__file__).resolve().parent
8
file_path = BASE_DIR / "data" / "test.txt"
9

10
print("目标文件路径：", file_path)
11
print("文件是否存在：", file_path.exists())
12

13
if file_path.exists():
14
    print(file_path.read_text(encoding="utf-8"))
15
else:
16
    print("文件不存在，请检查 data 文件夹是否和脚本在同一级目录")

展开收起

以后遇到文件找不到，可以先把这段代码复制进去看一下。

总结#

Python 路径问题的核心就是一句话：

1
相对路径相对的是当前工作目录，不一定是脚本所在目录。

如果想写稳定一点的脚本，就尽量用：

1
Path(__file__).resolve().parent

作为路径基准。

YOLO11 第一次预测图片

Mon, 29 Jun 2026 00:00:00 GMT

YOLO11 第一次预测图片#

前面已经记录过 YOLO11 的环境配置。环境装好以后，下一步最应该做的不是马上训练自己的数据集，而是先跑通一张图片的预测流程。

只要预测流程能跑通，就说明 Python 环境、依赖库、模型文件、显卡或 CPU 推理基本没有大问题。

1、准备文件目录#

可以先建立一个简单目录：

1
yolo_test/
2
├── yolo11n.pt
3
├── test.jpg
4
└── predict.py

其中：

yolo11n.pt 是预训练模型。
test.jpg 是需要检测的图片。
predict.py 是推理代码。

建议图片路径和模型路径先放在同一个目录中，这样可以减少路径错误。

2、安装 ultralytics#

进入对应的 conda 环境后执行：

Terminal window

1
pip install ultralytics

如果下载很慢，可以使用镜像源：

Terminal window

1
pip install ultralytics -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，可以测试一下：

Terminal window

1
yolo version

如果能输出版本号，说明命令行工具可以正常使用。

3、命令行预测#

最简单的预测方式是直接使用 yolo 命令：

Terminal window

1
yolo predict model=yolo11n.pt source=test.jpg

运行完成后，一般会生成类似目录：

1
runs/detect/predict/

里面会有标注好检测框的图片。

4、Python 代码预测#

也可以写成 Python 脚本：

1
from ultralytics import YOLO
2

3
# 加载模型
4
model = YOLO("yolo11n.pt")
5

6
# 执行预测
7
results = model.predict(
8
    source="test.jpg",
9
    save=True,
10
    conf=0.25
11
)
12

13
print("预测完成")
14
print(results)

运行：

Terminal window

1
python predict.py

参数说明：

source：输入图片路径，也可以是文件夹或视频。
save=True：保存预测结果。
conf=0.25：置信度阈值，低于这个值的检测框不显示。

5、查看检测结果#

如果运行成功，终端里会显示结果保存位置。一般是：

1
runs/detect/predict

打开里面的图片，如果能看到检测框和类别名称，说明第一次预测成功。

6、常见问题#

（1）找不到模型文件#

如果报错提示找不到 yolo11n.pt，先检查当前命令行所在目录：

Terminal window

1
pwd

Windows 可以使用：

Terminal window

1
cd

最简单的解决方式是使用绝对路径。

（2）CUDA 不可用#

可以在 Python 中检查：

1
import torch
2
print(torch.cuda.is_available())

如果输出 False，说明当前 PyTorch 没有识别到 GPU。这时先不要急着改 YOLO，应该回头检查显卡驱动、CUDA 版本和 PyTorch 版本是否匹配。

（3）预测速度很慢#

如果使用 CPU 推理，速度慢是正常的。可以先用小模型 yolo11n.pt 测试，等流程跑通后再考虑更大的模型。

总结#

YOLO11 学习建议按这个顺序来：

1
环境配置 -> 预训练模型预测 -> 理解输出结果 -> 准备自己的数据集 -> 训练模型

今天先完成第一步预测，只要能跑通 test.jpg，后面训练自己的数据集就更容易排查问题。

浏览器缓存导致页面未更新

Sun, 28 Jun 2026 00:00:00 GMT

浏览器缓存导致页面未更新#

线上文件已经更新，但浏览器还显示旧页面，这种情况很容易被误判成部署失败。浏览器缓存、CDN 缓存、服务器缓存都可能参与其中。

排查时要区分：服务器是否真的返回新内容，还是只有当前浏览器看到旧内容。

先用 curl 看服务器#

Terminal window

1
curl -I https://blog.tjcheng.cn/
2
curl -s https://blog.tjcheng.cn/api/allPostMeta.json | head

如果 curl 已经拿到新内容，问题多半在浏览器或中间缓存。

浏览器侧处理#

强制刷新：Windows 上通常是 Ctrl + F5。
使用无痕窗口打开。
开发者工具里勾选 Disable cache 后刷新。
清理特定站点缓存，而不是直接重装浏览器。

静态资源版本#

如果 JS/CSS 文件名没有哈希，浏览器可能长期缓存旧资源。构建工具通常会给资源加 hash，部署时要确认 HTML 和资源文件是同一批产物。

不要反复部署掩盖缓存问题#

如果服务器文件和接口都已经更新，重复构建上传没有意义。应该把注意力转到缓存层，确认响应头和浏览器行为。

实战复盘#

把《浏览器缓存导致页面未更新》写成可复用排查记录时，我会保留四类证据：原始现象、执行命令、关键输出、修复后的验证结果。少了其中任何一类，下次遇到类似问题都容易重新猜一遍。

排查类文章不要只写最终命令，还要写为什么先查这里。比如端口问题先看监听进程，Nginx 问题先分清 404 和 403，Python 环境问题先确认解释器路径。

如果修复动作有风险，例如杀进程、删文件、改服务配置，就应该写清回退方式。能恢复，才敢在服务器上操作。

最小验收样例#

验收《浏览器缓存导致页面未更新》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

页面未更新先分清服务器问题还是缓存问题。curl、无痕窗口和开发者工具，是最快的三步验证。

Git 大文件误提交处理

Sat, 27 Jun 2026 00:00:00 GMT

Git 大文件误提交处理#

大文件误提交会让仓库变慢，甚至导致远程推送失败。常见的大文件包括压缩包、模型权重、数据集、构建产物和日志。

处理时要区分：文件只是被加入暂存区，还是已经进入提交历史。

还没提交#

Terminal window

1
git status
2
git restore --staged big-file.zip

这只会取消暂存，不会删除工作区文件。

加入 .gitignore#

1
*.zip
2
dist/
3
node_modules/
4
*.pt
5
*.onnx
6
data/

忽略规则只对未被 Git 跟踪的文件生效。已经跟踪的文件需要先从索引移除。

已跟踪但想保留本地文件#

Terminal window

1
git rm --cached big-file.zip

然后提交 .gitignore 和索引变化，本地文件仍然保留。

已经进历史#

如果大文件已经进入提交历史，普通删除不会减少历史体积。需要使用 git filter-repo 或 BFG 清理历史，但这会影响协作分支，必须谨慎。

实战复盘#

把《Git 大文件误提交处理》写成可复用排查记录时，我会保留四类证据：原始现象、执行命令、关键输出、修复后的验证结果。少了其中任何一类，下次遇到类似问题都容易重新猜一遍。

排查类文章不要只写最终命令，还要写为什么先查这里。比如端口问题先看监听进程，Nginx 问题先分清 404 和 403，Python 环境问题先确认解释器路径。

如果修复动作有风险，例如杀进程、删文件、改服务配置，就应该写清回退方式。能恢复，才敢在服务器上操作。

最小验收样例#

验收《Git 大文件误提交处理》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

大文件处理越早越简单。提交前发现只需取消暂存；进入历史后再清理，就会影响整个仓库。

Linux 卡住进程处理

Fri, 26 Jun 2026 00:00:00 GMT

Linux 卡住进程处理#

服务器上遇到进程卡住，不应该第一反应就是 kill -9。强制结束可能导致文件没写完、锁没释放、服务状态不一致。

正确顺序是先定位，再尝试优雅停止，最后才强制结束。

找到进程#

Terminal window

1
ps aux | grep node
2
ss -lntp | grep ':3000'
3
top

如果是端口占用，ss -lntp 可以直接看到监听端口的进程。

优雅停止#

Terminal window

1
kill -TERM <pid>

TERM 会给进程机会清理资源。很多服务收到 TERM 后会正常退出。

强制结束#

Terminal window

1
kill -KILL <pid>

也就是常说的 kill -9。只有进程不响应 TERM，或者必须立即释放资源时再用。

结束后检查#

端口是否释放。
服务管理器是否自动重启。
日志里是否有异常。
临时文件和锁文件是否需要清理。

实战复盘#

把《Linux 卡住进程处理》写成可复用排查记录时，我会保留四类证据：原始现象、执行命令、关键输出、修复后的验证结果。少了其中任何一类，下次遇到类似问题都容易重新猜一遍。

排查类文章不要只写最终命令，还要写为什么先查这里。比如端口问题先看监听进程，Nginx 问题先分清 404 和 403，Python 环境问题先确认解释器路径。

如果修复动作有风险，例如杀进程、删文件、改服务配置，就应该写清回退方式。能恢复，才敢在服务器上操作。

最小验收样例#

验收《Linux 卡住进程处理》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

处理卡住进程要有顺序。先确认进程和影响范围，再优雅停止，强制结束只作为最后手段。

Linux 磁盘空间检查

Thu, 25 Jun 2026 00:00:00 GMT

Linux 磁盘空间检查#

服务器磁盘满了会引发很多看似无关的问题：构建失败、日志写不进去、数据库异常、上传文件失败。排查时先看磁盘，再看应用。

清理磁盘要先定位，不要盲目删除。

看整体空间#

Terminal window

1
df -h

Use% 接近 100% 的分区需要重点处理。还要注意 inode 是否耗尽。

Terminal window

1
df -ih

找大目录#

Terminal window

1
du -h --max-depth=1 /www/wwwroot | sort -h
2
du -h --max-depth=1 /var/log | sort -h

从大目录往下逐层看，找到真正占空间的文件，而不是凭感觉删。

常见可清理位置#

旧构建目录和旧 dist 备份，确认不需要后删除。
过大的应用日志，先备份或截断。
包管理器缓存。
临时上传文件。

清理前注意#

不要删除不了解的系统目录。删除日志前确认服务是否还在写；删除备份前确认有新的可回滚版本。

实战复盘#

把《Linux 磁盘空间检查》写成可复用排查记录时，我会保留四类证据：原始现象、执行命令、关键输出、修复后的验证结果。少了其中任何一类，下次遇到类似问题都容易重新猜一遍。

排查类文章不要只写最终命令，还要写为什么先查这里。比如端口问题先看监听进程，Nginx 问题先分清 404 和 403，Python 环境问题先确认解释器路径。

如果修复动作有风险，例如杀进程、删文件、改服务配置，就应该写清回退方式。能恢复，才敢在服务器上操作。

最小验收样例#

验收《Linux 磁盘空间检查》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

磁盘清理要先用 df 和 du 找证据。只删明确知道用途的文件，保留必要回滚空间。

SSH 连接超时排查

Wed, 24 Jun 2026 00:00:00 GMT

SSH 连接超时排查#

SSH 连接超时说明客户端没有在预期时间内和服务器建立连接。它和密码错误不同，密码错误至少说明网络已经通了。

排查 SSH 超时要从外到内：本地网络、服务器公网 IP、端口、防火墙、安全组、sshd 服务。

客户端先加详细日志#

Terminal window

1
ssh -vvv -o ConnectTimeout=8 root@8.141.117.145

-vvv 能看到连接停在哪一步。如果一直卡在 connecting，优先查网络和端口。

检查端口#

Terminal window

1
Test-NetConnection 8.141.117.145 -Port 22

端口不通时，不要继续试密码。先看云服务器安全组、防火墙和 sshd 是否监听。

服务器侧检查#

Terminal window

1
systemctl status sshd
2
ss -lntp | grep ':22'
3
iptables -S
4
ufw status

如果服务器能通过控制台登录，就从这些命令开始查。

常见原因#

云服务器安全组没有放行 22。
sshd 服务停止或端口被改。
本地网络阻断 22 端口。
服务器负载过高，响应很慢。

实战复盘#

把《SSH 连接超时排查》写成可复用排查记录时，我会保留四类证据：原始现象、执行命令、关键输出、修复后的验证结果。少了其中任何一类，下次遇到类似问题都容易重新猜一遍。

排查类文章不要只写最终命令，还要写为什么先查这里。比如端口问题先看监听进程，Nginx 问题先分清 404 和 403，Python 环境问题先确认解释器路径。

如果修复动作有风险，例如杀进程、删文件、改服务配置，就应该写清回退方式。能恢复，才敢在服务器上操作。

最小验收样例#

验收《SSH 连接超时排查》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

SSH 超时不是账号密码问题。先证明端口可达，再看 sshd 和登录认证，顺序清楚会省很多时间。

Nginx 404 与 403 排查

Tue, 23 Jun 2026 00:00:00 GMT

Nginx 404 与 403 排查#

Nginx 404 和 403 看起来都是页面打不开，但含义不同。404 通常是路径没找到，403 通常是权限或目录访问被拒绝。

排查时不要只刷新浏览器，要看 Nginx 配置、文件是否存在和错误日志。

先确认状态码#

Terminal window

1
curl -I https://blog.tjcheng.cn/posts/demo/

浏览器页面可能被前端路由或错误页包装，curl -I 能直接看到服务器返回状态。

404 的常见原因#

构建产物里没有对应 HTML。
Nginx root 指向了错误目录。
静态站路径需要 try_files，但配置没有回退到 index.html。
URL 末尾斜杠和实际生成路径不一致。

403 的常见原因#

文件或目录权限不足，Nginx 用户读不了。
访问的是目录，但没有 index 文件。
配置中禁止访问某些路径。
SELinux 或安全策略限制，具体看系统环境。

看日志#

Terminal window

1
nginx -t
2
tail -n 50 /www/wwwlogs/blog.tjcheng.cn.error.log
3
ls -lah /www/wwwroot/blog_app/blog_web_app/dist

错误日志通常会明确写 permission denied 或 No such file or directory，比猜测快得多。

实战复盘#

使用《Nginx 404 与 403 排查》时，我会先确认环境边界：本地还是服务器，Windows 还是 Linux，开发环境还是线上环境。很多命令本身没错，但换了系统或权限就会得到完全不同的结果。

排查记录的质量取决于可复现性。只要别人能按文章从现象走到验证，这篇文章就不是临时笔记，而是一张可靠的操作卡片。

最小验收样例#

验收《Nginx 404 与 403 排查》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

Nginx 排查要先区分 404 和 403。一个查路径和构建产物，一个查权限和访问规则。

Node 与 pnpm 版本检查

Mon, 22 Jun 2026 00:00:00 GMT

Node 与 pnpm 版本检查#

前端项目构建失败时，依赖版本和运行时版本是第一批要查的内容。Node 太旧、pnpm 版本不一致、lockfile 不匹配，都可能导致本地能跑服务器不能跑。

我会先确认版本，再安装依赖，最后构建。

查看版本#

Terminal window

1
node -v
2
pnpm -v
3
corepack --version

项目 README 或 package.json 里如果写了 engines，要优先按项目要求来。

使用 lockfile 安装#

Terminal window

1
pnpm install --frozen-lockfile

服务器部署时建议使用 frozen lockfile，避免自动改依赖版本导致构建结果不可控。

常见构建失败原因#

Node 版本低，不支持依赖使用的新语法。
pnpm 版本差异导致依赖解析不同。
lockfile 和 package.json 不一致。
服务器内存或磁盘不足。

记录部署环境#

每次成功部署后，可以记录 Node、pnpm、构建命令和构建耗时。以后出问题时，有一个可对比的基线。

实战复盘#

使用《Node 与 pnpm 版本检查》时，我会先确认环境边界：本地还是服务器，Windows 还是 Linux，开发环境还是线上环境。很多命令本身没错，但换了系统或权限就会得到完全不同的结果。

排查记录的质量取决于可复现性。只要别人能按文章从现象走到验证，这篇文章就不是临时笔记，而是一张可靠的操作卡片。

最小验收样例#

验收《Node 与 pnpm 版本检查》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

Node 和 pnpm 版本是前端部署的地基。先确认运行时和 lockfile，再追代码问题，排查会更快。

Jupyter kernel 缺失排查

Sun, 21 Jun 2026 00:00:00 GMT

Jupyter kernel 缺失排查#

Jupyter 能打开，不代表它使用的是项目虚拟环境。Notebook 里 import 失败，经常是因为当前 kernel 指向了另一个 Python。

解决思路是：在目标环境里安装 ipykernel，并把这个环境注册成 Jupyter kernel。

在虚拟环境中安装 ipykernel#

Terminal window

1
\.venv\Scripts\activate
2
python -m pip install ipykernel
3
python -m ipykernel install --user --name blog-venv --display-name "Python (blog-venv)"

注册后，Jupyter 的 kernel 列表里应该能看到 Python (blog-venv)。

确认 Notebook 使用的解释器#

1
import sys
2
print(sys.executable)

这个路径应该指向你的项目环境。如果不是，切换 kernel 后重新运行。

查看已有 kernel#

Terminal window

1
jupyter kernelspec list

常见问题#

在系统 Python 安装了包，但 Notebook 用的是 conda 环境。
注册 kernel 后没有重启 Jupyter 页面。
删除了虚拟环境，但 kernel 配置还留着。
包安装到了错误的 pip。

实战复盘#

使用《Jupyter kernel 缺失排查》时，我会先确认环境边界：本地还是服务器，Windows 还是 Linux，开发环境还是线上环境。很多命令本身没错，但换了系统或权限就会得到完全不同的结果。

排查记录的质量取决于可复现性。只要别人能按文章从现象走到验证，这篇文章就不是临时笔记，而是一张可靠的操作卡片。

最小验收样例#

验收《Jupyter kernel 缺失排查》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

Jupyter kernel 问题本质是解释器问题。Notebook 里打印 sys.executable，比猜测环境更可靠。

conda 环境导出与恢复

Sat, 20 Jun 2026 00:00:00 GMT

conda 环境导出与恢复#

conda 环境导出可以帮助复现实验，但导出的文件如果包含太多本机路径和平台依赖，迁移到另一台机器可能反而失败。

我会区分完整备份和跨平台分享两种场景。

完整导出#

Terminal window

1
conda env export -n myenv > environment.yml

这种方式适合在相似机器上恢复环境，信息最完整，但也可能包含平台相关依赖。

更干净的导出#

Terminal window

1
conda env export -n myenv --from-history > environment.yml

--from-history 只导出手动安装过的顶层包，更适合项目分享，但可能需要在新机器上重新解析依赖。

恢复环境#

Terminal window

1
conda env create -f environment.yml
2
conda activate myenv

如果环境名冲突，可以先修改 yml 里的 name 字段。

检查环境#

Python 版本是否一致。
CUDA、PyTorch、OpenCV 这类包是否匹配机器。
pip 安装的依赖是否也进入 yml。
是否包含本机绝对路径。

实战复盘#

使用《conda 环境导出与恢复》时，我会先确认环境边界：本地还是服务器，Windows 还是 Linux，开发环境还是线上环境。很多命令本身没错，但换了系统或权限就会得到完全不同的结果。

排查记录的质量取决于可复现性。只要别人能按文章从现象走到验证，这篇文章就不是临时笔记，而是一张可靠的操作卡片。

最小验收样例#

验收《conda 环境导出与恢复》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

conda 环境导出要看目的。自己备份用完整导出，给别人复现用更干净的历史导出，并写清关键版本。

pip 下载超时处理

Fri, 19 Jun 2026 00:00:00 GMT

pip 下载超时处理#

pip 下载超时通常不是包本身有问题，而是网络连接到 PyPI 不稳定。处理时先确认是偶发网络问题、镜像源问题，还是包版本和平台不匹配。

不要一失败就换一堆命令，先保留错误信息。

临时增加超时#

Terminal window

1
python -m pip install pandas --timeout 120 --retries 5

如果只是网络慢，增加 timeout 和 retries 就能解决。

使用镜像源#

Terminal window

1
python -m pip install pandas -i https://pypi.tuna.tsinghua.edu.cn/simple

镜像源适合下载慢的情况。但如果是包版本不存在，换源也没用。

先升级 pip#

Terminal window

1
python -m pip install --upgrade pip

较旧 pip 可能无法正确处理新格式 wheel，升级后再安装更稳。

离线或服务器环境#

服务器不能联网时，可以在本地下载 wheel，再上传安装。

Terminal window

1
python -m pip download -r requirements.txt -d wheels
2
python -m pip install --no-index --find-links wheels -r requirements.txt

实战复盘#

把《pip 下载超时处理》写成可复用排查记录时，我会保留四类证据：原始现象、执行命令、关键输出、修复后的验证结果。少了其中任何一类，下次遇到类似问题都容易重新猜一遍。

排查类文章不要只写最终命令，还要写为什么先查这里。比如端口问题先看监听进程，Nginx 问题先分清 404 和 403，Python 环境问题先确认解释器路径。

如果修复动作有风险，例如杀进程、删文件、改服务配置，就应该写清回退方式。能恢复，才敢在服务器上操作。

最小验收样例#

验收《pip 下载超时处理》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

pip 超时先判断网络，再处理源和重试。安装失败时保留完整错误，比盲目换命令更有效。

Python 虚拟环境激活问题

Thu, 18 Jun 2026 00:00:00 GMT

Python 虚拟环境激活问题#

Python 虚拟环境的目标是让项目使用独立依赖。激活失败时，不要急着重装 Python，先确认 venv 是否创建成功、脚本路径是否正确、当前解释器是谁。

很多问题其实是终端没有进入项目目录，或者 PowerShell 执行策略阻止了激活脚本。

创建和激活#

Terminal window

1
python -m venv .venv
2
.\.venv\Scripts\Activate.ps1
3
python -V
4
python -c "import sys; print(sys.executable)"

最后一行应该指向项目里的 .venv，而不是系统 Python。

执行策略问题#

如果 PowerShell 提示脚本被禁止运行，可以只对当前用户放宽执行策略。

Terminal window

1
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

不激活也能使用#

激活只是方便修改 PATH。也可以直接调用虚拟环境里的 Python。

Terminal window

1
.\.venv\Scripts\python.exe -m pip install pandas

检查依赖装到哪里#

Terminal window

1
python -m pip -V
2
python -m pip list

如果 pip -V 显示的路径不是 .venv，说明依赖可能装到别的环境里了。

实战复盘#

复盘《Python 虚拟环境激活问题》时，我会把它拆成“现象 -> 定位 -> 处理 -> 验证”。现象负责描述用户看到了什么，定位负责缩小范围，处理负责改动系统，验证负责证明问题真的解决。

这类文章最忌讳只堆命令。命令旁边要说明它回答了什么问题，例如 df -h 回答磁盘是否满，ss -lntp 回答端口由谁监听，sys.executable 回答 Notebook 到底用哪个 Python。

以后遇到新变体，可以把新增现象补到同一篇文章里，而不是另开一篇相似记录。排查文章越集中，越有复用价值。

最小验收样例#

验收《Python 虚拟环境激活问题》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

虚拟环境排查要围绕解释器路径。确认当前 Python 来自 .venv，比只看命令前缀有没有括号更可靠。

PowerShell 环境变量设置

Wed, 17 Jun 2026 00:00:00 GMT

PowerShell 环境变量设置#

环境变量问题经常表现为“我明明设置了，程序还是读不到”。原因通常是设置范围不对：当前终端、用户级、系统级、生效进程并不一样。

排查时先确认变量在哪个进程里可见。

当前会话临时变量#

Terminal window

1
$env:API_KEY = "test-value"
2
python -c "import os; print(os.getenv('API_KEY'))"

这种写法只对当前 PowerShell 窗口和它启动的子进程有效。关闭窗口后就没了。

持久用户变量#

Terminal window

1
[Environment]::SetEnvironmentVariable("API_KEY", "test-value", "User")

设置后通常需要重新打开终端，已经运行的程序不会自动拿到新值。

查看变量#

Terminal window

1
Get-ChildItem Env:
2
$env:PATH -split ';'

常见问题#

在一个终端设置变量，却在另一个已经打开的终端运行程序。
变量名大小写混用，跨平台时表现不同。
把值写进命令历史，泄露敏感信息。
修改 PATH 后没有重新打开终端。

实战复盘#

把《PowerShell 环境变量设置》写成可复用排查记录时，我会保留四类证据：原始现象、执行命令、关键输出、修复后的验证结果。少了其中任何一类，下次遇到类似问题都容易重新猜一遍。

排查类文章不要只写最终命令，还要写为什么先查这里。比如端口问题先看监听进程，Nginx 问题先分清 404 和 403，Python 环境问题先确认解释器路径。

如果修复动作有风险，例如杀进程、删文件、改服务配置，就应该写清回退方式。能恢复，才敢在服务器上操作。

最小验收样例#

验收《PowerShell 环境变量设置》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

PowerShell 环境变量要区分临时和持久，也要记住进程边界。程序读不到变量时，先在同一个终端里打印确认。

Windows 路径空格问题排查

Tue, 16 Jun 2026 00:00:00 GMT

Windows 路径空格问题排查#

Windows 路径里带空格很常见，例如 Program Files。命令行如果没有正确加引号，工具会把一个路径拆成多个参数。

排查这类问题时，先看命令实际收到的路径，而不是只看文件是否存在。

加引号是第一步#

Terminal window

1
cd "E:\Project Data\blog app"
2
python "E:\Project Data\scripts\run.py"

路径包含空格时，整段路径都要放进引号。不要只给某一部分加。

PowerShell 调用程序#

PowerShell 里调用带空格路径的可执行文件，可以使用调用运算符 &。

Terminal window

1
& "C:\Program Files\nodejs\node.exe" --version

优先使用 Path 对象#

在 Python 脚本里，尽量使用 pathlib.Path 拼路径，不要手写字符串拼接。

1
from pathlib import Path
2

3
root = Path(r"E:\Project Data\blog app")
4
file = root / "src" / "content" / "posts"
5
print(file)

常见误判#

文件存在，但命令把路径拆开了。
相对路径基于当前工作目录，不是脚本目录。
PowerShell、cmd、Git Bash 的转义规则不同。

实战复盘#

使用《Windows 路径空格问题排查》时，我会先确认环境边界：本地还是服务器，Windows 还是 Linux，开发环境还是线上环境。很多命令本身没错，但换了系统或权限就会得到完全不同的结果。

排查记录的质量取决于可复现性。只要别人能按文章从现象走到验证，这篇文章就不是临时笔记，而是一张可靠的操作卡片。

最小验收样例#

验收《Windows 路径空格问题排查》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

Windows 路径问题多数不是文件不存在，而是参数被拆错。带空格路径一律加引号，脚本里优先用路径库。

视觉模型错误案例整理

Mon, 15 Jun 2026 00:00:00 GMT

视觉模型错误案例整理#

错误案例不是训练失败的附属品，而是下一轮改进最有价值的数据。模型在哪些场景错，往往比平均指标更能说明问题。

我会把错误案例按类型保存，并记录出现原因和后续动作。

错误类型#

漏检：目标存在但没有预测框。
误检：背景或无关物体被预测为目标。
类别错：框位置对但类别错。
定位差：框偏移、过大或过小。
数据问题：标注本身错误或图片质量太差。

目录组织#

1
error_cases/
2
  missed/
3
  false_positive/
4
  wrong_class/
5
  bad_box/
6
  label_issue/

目录名直接对应错误类型，后面回看时不用重新判断。

记录字段#

除了保存图片，还应该记录模型版本、数据版本、预测参数、错误说明和建议动作。否则过一段时间就只剩一堆不知道为什么保存的图片。

如何使用错误案例#

如果同类错误集中出现，就补充对应场景数据；如果错误来自标注问题，就先修数据；如果是小目标普遍漏检，再考虑输入尺寸、模型结构或训练策略。

实战复盘#

复用《视觉模型错误案例整理》时，我会先用三到五张图片跑通流程，再扩大到完整数据集。小样本阶段要故意覆盖正常图、边界图和可能失败的图，而不是只选最干净的样本。

OpenCV 和 YOLO 相关步骤都要特别关注坐标和尺寸。图片数组常用高宽顺序，检测框常用 x/y 顺序，YOLO 又使用归一化中心点坐标，混用后不会总是报错，但结果一定会偏。

后续如果要写成更完整教程，可以补充输入目录结构、输出目录结构和一张可视化样例，让读者能直接对照自己的项目。

最小验收样例#

验收《视觉模型错误案例整理》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

错误案例库是模型迭代的导航。把错误分门别类，比盲目继续训练更能找到改进方向。

模型结果对比记录

Sun, 14 Jun 2026 00:00:00 GMT

模型结果对比记录#

模型对比最怕比较条件不一致。不同数据划分、不同 conf 阈值、不同输入尺寸下得到的结果，不能直接说明哪个模型更好。

我做结果对比时，会先固定评估集和推理参数，再看指标和错误案例。

固定比较条件#

使用同一份验证集。
使用相同输入尺寸。
使用相同 conf 和 iou 参数。
记录模型权重、训练轮数和数据版本。

指标和实际效果一起看#

mAP、precision、recall 是整体指标，但实际使用还要看典型图片。一个模型指标略高，却在关键场景漏检，也未必更适合上线。

对比表模板#

1
模型 | 数据版本 | imgsz | conf | mAP50 | recall | 备注
2
yolov8n | v1 | 640 | 0.25 | 0.82 | 0.76 | 小目标漏检
3
yolov8s | v1 | 640 | 0.25 | 0.86 | 0.81 | 推理稍慢

错误案例库#

把每个模型失败的图片放到同一个目录，按漏检、误检、类别错、框不准分类。看错误案例比只看平均指标更容易找到下一步改进方向。

实战复盘#

把《模型结果对比记录》用于真实视觉项目时，我会先做可视化抽查。图像任务里很多错误不会抛异常，例如颜色通道反了、检测框偏移、标签和图片不同步，但一张可视化结果就能暴露。

每个处理步骤都应该保存少量中间结果：原图、处理后图片、mask、绘制框图片或预测输出。不要只保存最终模型指标，因为指标无法告诉你是哪一步把数据处理坏了。

如果文章涉及批量处理，还要记录成功数量、失败数量和失败样本路径。视觉项目的数据量一大，没有失败清单就很难复查。

最小验收样例#

验收《模型结果对比记录》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

模型对比要固定条件，再比较指标和错误案例。否则看似精确的数字，可能只是评估环境变化带来的假差异。

标注质量检查清单

Sat, 13 Jun 2026 00:00:00 GMT

标注质量检查清单#

模型训练质量很大程度取决于标注质量。标注错了，模型会认真学习错误答案。

标注检查不能只看文件数量，还要看类别是否一致、框是否贴合、是否漏标，以及图片和标签是否一一对应。

文件一致性#

每张图片是否有对应标签文件。
空标签是否代表没有目标，而不是漏标。
标签文件是否能被解析。
类别编号是否在配置范围内。

框位置检查#

随机抽取一批图片，把标注框画出来。看框是否覆盖完整目标，是否包含太多背景，是否把多个目标框成一个。

漏标和错标#

漏标比框稍微不准更危险。模型看到图片里有目标却没有标签，会把真实目标当背景学习。错标则会混淆类别边界。

抽检策略#

不要只抽容易的图片。应该覆盖不同类别、不同光照、不同角度、不同来源。对少数类要提高抽检比例。

实战复盘#

检查《标注质量检查清单》这类视觉流程时，我不会只看命令是否完成，而会打开输出文件。视觉任务的质量判断必须回到图像本身：目标是否还在、颜色是否正常、框是否贴合、类别是否正确。

如果处理结果准备进入训练集，我会额外记录数据版本。图片、标签、划分文件和增强策略要能对应到同一个版本，否则模型结果变化时很难解释。

这类文章最适合持续补充错误案例。每遇到一次读图失败、标注错位或预测异常，都可以回到文章里增加一个真实排查点。

最小验收样例#

验收《标注质量检查清单》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

标注质量检查要把文件、类别、框位置和漏标分开看。训练前多花时间抽检，能避免后面反复怀疑模型。

视频抽帧处理笔记

Fri, 12 Jun 2026 00:00:00 GMT

视频抽帧处理笔记#

视频抽帧是制作视觉数据集的常见方法，但直接每帧都保存会产生大量重复图片。抽帧策略要根据目标变化速度和标注成本来定。

抽得太密，数据重复；抽得太稀，容易错过关键动作。

按间隔抽帧#

1
import cv2
2
from pathlib import Path
3

4
video = cv2.VideoCapture("demo.mp4")
5
out_dir = Path("frames")
6
out_dir.mkdir(exist_ok=True)
7

8
frame_id = 0
9
saved = 0
10
while True:
11
    ok, frame = video.read()
12
    if not ok:
13
        break
14
    if frame_id % 30 == 0:
15
        cv2.imwrite(str(out_dir / f"frame_{frame_id:06d}.jpg"), frame)
16
        saved += 1
17
    frame_id += 1
18

19
print("frames", frame_id, "saved", saved)

展开收起

命名要可追溯#

文件名最好包含视频名和帧号，例如 camera01_000300.jpg。以后发现某张图有问题，可以回到原视频定位。

抽帧后去重#

固定间隔抽帧仍然可能产生大量相似图。可以先按场景或时间段抽样查看，再决定是否需要感知哈希去重。

质量检查#

是否有黑屏、花屏、模糊帧。
目标是否足够清晰。
不同场景是否覆盖。
抽帧数量是否和标注人力匹配。

实战复盘#

把《视频抽帧处理笔记》用于真实视觉项目时，我会先做可视化抽查。图像任务里很多错误不会抛异常，例如颜色通道反了、检测框偏移、标签和图片不同步，但一张可视化结果就能暴露。

如果文章涉及批量处理，还要记录成功数量、失败数量和失败样本路径。视觉项目的数据量一大，没有失败清单就很难复查。

最小验收样例#

验收《视频抽帧处理笔记》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

视频抽帧要在覆盖场景和控制重复之间取平衡。命名可追溯、抽样检查清楚，后续标注才不会失控。

批量图片推理流程

Thu, 11 Jun 2026 00:00:00 GMT

批量图片推理流程#

单张图片预测成功，只能说明模型接口能跑。真正使用时往往需要批量推理，这时路径、异常处理、输出命名和结果统计更重要。

批量流程要做到一张图失败不影响全部任务，同时能回头找到失败原因。

遍历输入#

1
from pathlib import Path
2

3
image_dir = Path("images")
4
images = sorted(image_dir.glob("*.jpg"))
5
print("total", len(images))

先打印数量，确认实际读取的图片和预期一致。扩展名大小写也要考虑。

记录失败#

1
bad = []
2
for p in images:
3
    img = cv2.imread(str(p))
4
    if img is None:
5
        bad.append((str(p), "read_failed"))
6
        continue
7
    # result = model(img)
8

9
print("failed", len(bad))
10
print(bad[:10])

输出结构#

我习惯把可视化图片、预测 txt、统计 csv 分开放，避免结果目录混乱。

1
outputs/
2
  vis/
3
  labels/
4
  summary.csv
5
  failed.txt

批量后统计#

成功处理多少张。
失败多少张，失败原因是什么。
每类预测数量。
平均耗时和最慢样本。

实战复盘#

复用《批量图片推理流程》时，我会先用三到五张图片跑通流程，再扩大到完整数据集。小样本阶段要故意覆盖正常图、边界图和可能失败的图，而不是只选最干净的样本。

后续如果要写成更完整教程，可以补充输入目录结构、输出目录结构和一张可视化样例，让读者能直接对照自己的项目。

最小验收样例#

验收《批量图片推理流程》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

批量推理不是把单张预测套循环。稳定的输入遍历、失败记录和结果目录，决定了后续能不能复查。

图像增强基础笔记

Wed, 10 Jun 2026 00:00:00 GMT

图像增强基础笔记#

图像增强可以提升模型对光照、角度、尺度变化的适应能力，但增强不是越多越好。错误的增强会让图片和标签不一致，甚至改变类别含义。

我使用增强前会先问：这种变化在真实场景中会出现吗？

常见增强#

翻转：适合左右对称或方向不敏感的目标。
缩放和裁剪：模拟距离变化，但要避免裁掉目标主体。
亮度和对比度：模拟光照变化。
模糊和噪声：模拟拍摄质量变化。
旋转：要确认目标方向是否仍然合理。

增强必须同步标签#

检测任务中，如果图片翻转、裁剪或缩放，框坐标也要同步变换。只增强图片不改标签，会直接制造错误训练样本。

先可视化一批#

1
# 使用任意增强库后，都建议保存一批增强结果
2
out_dir = Path("outputs/aug_check")
3
out_dir.mkdir(parents=True, exist_ok=True)
4
# 保存增强后的图片和框，用肉眼检查是否合理

增强策略上线前，至少看几十张增强后的图片和标注框。

不适合增强的情况#

文字识别里水平翻转可能让文字变成无意义图像；医学或工业缺陷场景中，颜色变化可能改变判断依据；方向敏感目标不能随意旋转。

实战复盘#

复用《图像增强基础笔记》时，我会先用三到五张图片跑通流程，再扩大到完整数据集。小样本阶段要故意覆盖正常图、边界图和可能失败的图，而不是只选最干净的样本。

后续如果要写成更完整教程，可以补充输入目录结构、输出目录结构和一张可视化样例，让读者能直接对照自己的项目。

最小验收样例#

验收《图像增强基础笔记》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

图像增强的目标是模拟真实变化，不是随机制造图片。每一种增强都要能解释，并通过可视化检查标签是否仍然正确。

数据集 train val 划分

Tue, 09 Jun 2026 00:00:00 GMT

数据集 train val 划分#

训练集和验证集划分决定了模型评估是否可信。划分不当时，验证指标可能很好看，但真实新数据表现很差。

视觉任务里最常见的坑是相似图片同时出现在 train 和 val，造成数据泄漏。

基本划分#

1
from sklearn.model_selection import train_test_split
2

3
images = sorted(list(Path("images").glob("*.jpg")))
4
train, val = train_test_split(images, test_size=0.2, random_state=42)
5
print(len(train), len(val))

random_state 能保证划分可复现。以后重新训练时，不会因为划分变化导致结果无法比较。

按主体划分#

如果同一个物体、同一个视频、同一个场景产生了多张图片，应该按主体或视频划分，而不是按单张图片随机划分。

例如视频抽帧任务里，相邻帧非常相似。如果前一帧在训练集，后一帧在验证集，指标会虚高。

保持类别分布#

类别不平衡时，要检查 train 和 val 中每个类别是否都有样本。少数类如果只出现在训练集，验证指标就看不到它的效果。

划分后检查#

图片和标签是否同步移动。
train/val 是否有重名文件交叉。
每个类别在两边的数量。
验证集是否代表真实使用场景。

实战复盘#

检查《数据集 train val 划分》这类视觉流程时，我不会只看命令是否完成，而会打开输出文件。视觉任务的质量判断必须回到图像本身：目标是否还在、颜色是否正常、框是否贴合、类别是否正确。

如果处理结果准备进入训练集，我会额外记录数据版本。图片、标签、划分文件和增强策略要能对应到同一个版本，否则模型结果变化时很难解释。

这类文章最适合持续补充错误案例。每遇到一次读图失败、标注错位或预测异常，都可以回到文章里增加一个真实排查点。

最小验收样例#

验收《数据集 train val 划分》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

数据集划分不是简单随机切一刀。要防止泄漏、保持类别分布，并保证验证集能代表真实问题。

YOLO conf 与 iou 参数

Mon, 08 Jun 2026 00:00:00 GMT

YOLO conf 与 iou 参数#

YOLO 预测时常见两个参数：conf 控制置信度阈值，iou 控制 NMS 合并重叠框的力度。它们不会改变模型权重，但会改变最终输出结果。

调这两个参数时，要结合误检和漏检来看，不能只追求框数量多或少。

conf 影响低置信度框#

conf 越高，输出框越少，误检可能减少，但漏检可能增加。conf 越低，能看到更多候选框，但也会带来更多噪声。

Terminal window

1
yolo detect predict model=best.pt source=images conf=0.25

iou 影响重叠框合并#

iou 用于非极大值抑制。多个框重叠同一个目标时，NMS 会保留更合适的框。阈值设置不当时，可能出现重复框或过度合并。

Terminal window

1
yolo detect predict model=best.pt source=images conf=0.25 iou=0.7

调参顺序#

我一般先固定 iou，调整 conf 看漏检和误检变化；再根据重复框情况微调 iou。每次只改一个参数，避免不知道结果变化来自哪里。

记录实验#

参数组合。
输出框数量。
典型漏检图片。
典型误检图片。
是否满足业务场景更看重召回还是精度。

实战复盘#

把《YOLO conf 与 iou 参数》用于真实视觉项目时，我会先做可视化抽查。图像任务里很多错误不会抛异常，例如颜色通道反了、检测框偏移、标签和图片不同步，但一张可视化结果就能暴露。

如果文章涉及批量处理，还要记录成功数量、失败数量和失败样本路径。视觉项目的数据量一大，没有失败清单就很难复查。

最小验收样例#

验收《YOLO conf 与 iou 参数》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

conf 和 iou 是预测后处理参数。调它们要围绕误检、漏检和重复框做对比，而不是凭感觉选一个数。

YOLO 预测结果检查

Sun, 07 Jun 2026 00:00:00 GMT

YOLO 预测结果检查#

YOLO 预测命令跑完并不代表模型可用。真正需要看的是输出图片、检测框、类别、置信度和失败案例。

我会把预测结果当成一次数据审查：哪些图检测得好，哪些图漏检，哪些图误检。

保存预测结果#

Terminal window

1
yolo detect predict model=runs/detect/train/weights/best.pt source=images/val save=True save_txt=True save_conf=True

save_txt 会保存预测框文本，save_conf 会把置信度也写进去，方便后续统计。

看输出目录#

预测结果通常保存在 runs/detect/predict 或带编号的目录中。先打开可视化图片，不要只看终端输出。

统计预测数量#

1
from pathlib import Path
2

3
label_dir = Path("runs/detect/predict/labels")
4
counts = [len(p.read_text().splitlines()) for p in label_dir.glob("*.txt")]
5
print("images", len(counts))
6
print("avg boxes", sum(counts) / max(len(counts), 1))

错误案例分类#

漏检：目标存在但没有框。
误检：背景被框成目标。
类别错：框位置对，但类别错。
框不准：框偏大、偏小或偏移。

实战复盘#

复用《YOLO 预测结果检查》时，我会先用三到五张图片跑通流程，再扩大到完整数据集。小样本阶段要故意覆盖正常图、边界图和可能失败的图，而不是只选最干净的样本。

后续如果要写成更完整教程，可以补充输入目录结构、输出目录结构和一张可视化样例，让读者能直接对照自己的项目。

最小验收样例#

验收《YOLO 预测结果检查》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

预测结果检查要从可视化开始，再进入统计。只看 mAP 或终端日志，容易忽略实际使用中的错误类型。

YOLO 小样本训练验证

Sat, 06 Jun 2026 00:00:00 GMT

YOLO 小样本训练验证#

正式训练前，我喜欢先用几十张图片跑一个小样本训练。它不是为了得到好模型，而是验证数据路径、标注格式、类别配置和训练流程能跑通。

如果小样本都学不动，直接上完整数据集只会浪费时间。

小样本要验证什么#

图片路径是否正确。
标签是否能被读取。
类别数量和 names 是否一致。
loss 是否下降。
预测结果是否能在训练样本上框到目标。

数据配置重点#

1
path: dataset
2
train: images/train
3
val: images/val
4
names:
5
  0: person
6
  1: car

names 的数量要和标签里的类别编号匹配。标签里出现类别 2，但 names 只有 0 和 1，就一定有问题。

训练命令示例#

Terminal window

1
yolo detect train data=data.yaml model=yolov8n.pt epochs=20 imgsz=640 batch=8

小样本阶段可以用轻量模型和较少 epoch，重点看流程和过拟合能力。

怎么判断结果#

小样本训练后，在训练集图片上预测。如果模型完全框不到目标，要优先检查标注是否错位、类别是否错、图片和标签是否对应，而不是急着调学习率。

实战复盘#

检查《YOLO 小样本训练验证》这类视觉流程时，我不会只看命令是否完成，而会打开输出文件。视觉任务的质量判断必须回到图像本身：目标是否还在、颜色是否正常、框是否贴合、类别是否正确。

如果处理结果准备进入训练集，我会额外记录数据版本。图片、标签、划分文件和增强策略要能对应到同一个版本，否则模型结果变化时很难解释。

这类文章最适合持续补充错误案例。每遇到一次读图失败、标注错位或预测异常，都可以回到文章里增加一个真实排查点。

最小验收样例#

验收《YOLO 小样本训练验证》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

YOLO 小样本训练是正式训练前的体检。先证明数据和流程没问题，再扩大数据量和训练时间。

YOLO 标注格式检查

Fri, 05 Jun 2026 00:00:00 GMT

YOLO 标注格式检查#

YOLO 标注格式看起来只有五列，但写错一列就会让训练结果异常。最常见的问题是坐标没有归一化、类别编号越界、中心点和左上角坐标混用。

训练前先抽查标签文件，比训练失败后再回头找原因省很多时间。

YOLO 一行标注的含义#

1
class_id x_center y_center width height

x_center、y_center、width、height 都是 0 到 1 之间的归一化值，基于图片宽高计算，不是像素坐标。

格式检查脚本#

1
from pathlib import Path
2

3
for txt in Path("labels").glob("*.txt"):
4
    for i, line in enumerate(txt.read_text().splitlines(), 1):
5
        parts = line.split()
6
        if len(parts) != 5:
7
            print("bad columns", txt, i, line)
8
            continue
9
        cls, *box = parts
10
        values = list(map(float, box))
11
        if not all(0 <= v <= 1 for v in values):
12
            print("out of range", txt, i, line)

和图片一一对应#

图片和标签通常要求同名不同后缀，例如 images/a.jpg 对应 labels/a.txt。缺标签文件不一定报错，但会影响训练样本。

可视化验证#

把归一化坐标还原成像素坐标后画出来，才能确认框是否真的对准目标。只检查数字范围不能发现中心点和左上角混用的问题。

实战复盘#

复用《YOLO 标注格式检查》时，我会先用三到五张图片跑通流程，再扩大到完整数据集。小样本阶段要故意覆盖正常图、边界图和可能失败的图，而不是只选最干净的样本。

后续如果要写成更完整教程，可以补充输入目录结构、输出目录结构和一张可视化样例，让读者能直接对照自己的项目。

最小验收样例#

验收《YOLO 标注格式检查》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

YOLO 标注检查要同时看格式、范围、类别和可视化结果。数字合法不代表框一定正确。

OpenCV 绘制检测框

Thu, 04 Jun 2026 00:00:00 GMT

OpenCV 绘制检测框#

检测框可视化是检查模型和标注质量最直接的方法。只看 txt 坐标或预测数组，很难发现框偏移、类别错位和尺度问题。

我通常在训练前画标注框，预测后画结果框，两边都看。

绘制矩形框#

1
img = cv2.imread("demo.jpg")
2
x1, y1, x2, y2 = 50, 40, 220, 180
3
cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
4
cv2.imwrite("box.jpg", img)

OpenCV 颜色是 BGR，所以绿色是 (0, 255, 0)。

添加文字#

1
label = "person 0.92"
2
cv2.putText(
3
    img, label, (x1, max(20, y1 - 8)),
4
    cv2.FONT_HERSHEY_SIMPLEX, 0.6,
5
    (0, 255, 0), 2,
6
)

文字位置要防止超出图片顶部，所以可以对 y 坐标做 max。

批量可视化#

批量画框时，不要覆盖原图。保存到单独的 outputs/vis 目录，便于对照原始图片。

1
from pathlib import Path
2

3
out_dir = Path("outputs/vis")
4
out_dir.mkdir(parents=True, exist_ok=True)
5
cv2.imwrite(str(out_dir / "demo_vis.jpg"), img)

检查重点#

框是否覆盖目标，不偏移。
类别文字是否和目标一致。
坐标是 xyxy 还是 xywh，没有混用。
归一化坐标是否已经还原到像素坐标。

实战复盘#

把《OpenCV 绘制检测框》用于真实视觉项目时，我会先做可视化抽查。图像任务里很多错误不会抛异常，例如颜色通道反了、检测框偏移、标签和图片不同步，但一张可视化结果就能暴露。

如果文章涉及批量处理，还要记录成功数量、失败数量和失败样本路径。视觉项目的数据量一大，没有失败清单就很难复查。

最小验收样例#

验收《OpenCV 绘制检测框》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

画框不是展示效果图，而是排查数据和模型问题。任何检测任务都值得先做可视化抽查。

OpenCV 轮廓检测笔记

Wed, 03 Jun 2026 00:00:00 GMT

OpenCV 轮廓检测笔记#

轮廓检测常用于从二值图里找目标边界。它依赖前一步的分割质量，所以不要跳过 mask 检查直接找轮廓。

如果二值图噪声很多，轮廓数量会暴涨，后续过滤就会很混乱。

输入必须是二值图#

1
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
2
_, mask = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
3
contours, hierarchy = cv2.findContours(
4
    mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
5
)
6
print(len(contours))

RETR_EXTERNAL 只取外层轮廓，适合多数目标检测前处理；如果需要内部孔洞，再考虑其他模式。

按面积过滤#

1
boxes = []
2
for cnt in contours:
3
    area = cv2.contourArea(cnt)
4
    if area < 100:
5
        continue
6
    x, y, w, h = cv2.boundingRect(cnt)
7
    boxes.append((x, y, w, h, area))

面积阈值要根据图片分辨率调整，不能从一张图直接套到所有数据。

画出结果检查#

1
vis = img.copy()
2
for x, y, w, h, area in boxes:
3
    cv2.rectangle(vis, (x, y), (x + w, y + h), (0, 255, 0), 2)
4
cv2.imwrite("contours_check.jpg", vis)

常见问题#

mask 黑白反了，导致背景成为最大轮廓。
噪声没有过滤，小碎点太多。
轮廓模式选错，内部边界也被算进来。
坐标和宽高后续转换成检测框时写反。

实战复盘#

复用《OpenCV 轮廓检测笔记》时，我会先用三到五张图片跑通流程，再扩大到完整数据集。小样本阶段要故意覆盖正常图、边界图和可能失败的图，而不是只选最干净的样本。

后续如果要写成更完整教程，可以补充输入目录结构、输出目录结构和一张可视化样例，让读者能直接对照自己的项目。

最小验收样例#

验收《OpenCV 轮廓检测笔记》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

轮廓检测要从二值图质量开始检查。mask 清楚、面积阈值合理，轮廓结果才有使用价值。

OpenCV 阈值分割基础

Tue, 02 Jun 2026 00:00:00 GMT

OpenCV 阈值分割基础#

阈值分割适合把灰度图按亮暗分成前景和背景。它简单、直观，但前提是目标和背景在灰度上确实有差异。

如果光照变化很大，固定阈值往往不稳定，需要考虑自适应阈值或先做预处理。

固定阈值#

1
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
2
_, mask = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
3
cv2.imwrite("mask.png", mask)

返回值里的第一个值是实际阈值，第二个才是二值图。

Otsu 自动阈值#

1
threshold, mask = cv2.threshold(
2
    gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU
3
)
4
print("otsu threshold", threshold)

Otsu 适合前景和背景灰度分布比较分开的情况。

自适应阈值#

1
mask = cv2.adaptiveThreshold(
2
    gray, 255,
3
    cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
4
    cv2.THRESH_BINARY,
5
    21, 5,
6
)

局部光照差异明显时，自适应阈值比全局阈值更稳。

结果检查#

前景是否被完整保留。
背景噪声是否过多。
黑白是否反了，必要时使用 THRESH_BINARY_INV。
阈值前是否需要模糊降噪。

实战复盘#

复用《OpenCV 阈值分割基础》时，我会先用三到五张图片跑通流程，再扩大到完整数据集。小样本阶段要故意覆盖正常图、边界图和可能失败的图，而不是只选最干净的样本。

后续如果要写成更完整教程，可以补充输入目录结构、输出目录结构和一张可视化样例，让读者能直接对照自己的项目。

最小验收样例#

验收《OpenCV 阈值分割基础》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

阈值分割的关键是看图，不是只看代码。每次调整阈值后都要保存 mask，确认它真的分出了目标。

OpenCV resize 与裁剪

Mon, 01 Jun 2026 00:00:00 GMT

OpenCV resize 与裁剪#

resize 和 crop 是视觉任务里最基础的预处理，但也最容易写错宽高顺序。OpenCV 的 resize 参数是 (width, height)，而图片 shape 是 (height, width, channels)。

只要这两个顺序混淆，图片比例就会变形，后面的标注和模型输入都会出问题。

resize 的宽高顺序#

1
img = cv2.imread("demo.jpg")
2
h, w = img.shape[:2]
3
resized = cv2.resize(img, (640, 480))  # width=640, height=480
4
print(w, h, resized.shape)

我通常显式写注释，提醒自己传入的是宽、高。

保持比例缩放#

1
target_w = 640
2
scale = target_w / w
3
target_h = int(h * scale)
4
resized = cv2.resize(img, (target_w, target_h))

如果不想图像变形，就不要强行拉到固定宽高。目标模型需要固定尺寸时，可以再做 padding。

裁剪要检查边界#

1
x1, y1, x2, y2 = 100, 80, 300, 260
2
x1 = max(0, x1)
3
y1 = max(0, y1)
4
x2 = min(w, x2)
5
y2 = min(h, y2)
6
crop = img[y1:y2, x1:x2]

数组裁剪顺序是 [y1:y2, x1:x2]，也就是先高后宽。

和标注联动#

如果图片做了 resize 或 crop，检测框坐标也必须同步变换。只改图片不改标注，会让训练数据直接错位。

实战复盘#

检查《OpenCV resize 与裁剪》这类视觉流程时，我不会只看命令是否完成，而会打开输出文件。视觉任务的质量判断必须回到图像本身：目标是否还在、颜色是否正常、框是否贴合、类别是否正确。

如果处理结果准备进入训练集，我会额外记录数据版本。图片、标签、划分文件和增强策略要能对应到同一个版本，否则模型结果变化时很难解释。

这类文章最适合持续补充错误案例。每遇到一次读图失败、标注错位或预测异常，都可以回到文章里增加一个真实排查点。

最小验收样例#

验收《OpenCV resize 与裁剪》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

OpenCV 预处理要始终区分 shape 的高宽和 resize 参数的宽高。图片变换后，标注也要一起变换。

OpenCV 颜色空间转换

Sun, 31 May 2026 00:00:00 GMT

OpenCV 颜色空间转换#

OpenCV 默认读取彩色图是 BGR，而很多可视化工具和深度学习库习惯 RGB。颜色空间搞错时，图片不会报错，但颜色会明显不对。

这类问题很隐蔽，因为数组形状完全正常，只有显示效果异常。

BGR 转 RGB#

1
import cv2
2
import matplotlib.pyplot as plt
3

4
img_bgr = cv2.imread("demo.jpg")
5
img_rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB)
6
plt.imshow(img_rgb)
7
plt.axis("off")

用 matplotlib 显示 OpenCV 图片时，基本都要先转 RGB。

转灰度#

1
gray = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2GRAY)
2
print(gray.shape)  # 只有高和宽，没有通道维度

边缘检测、阈值分割、轮廓检测前，经常会先转灰度。

HSV 的用途#

HSV 更适合按颜色范围做分割。比如提取某种颜色的区域时，直接在 RGB/BGR 上设阈值不如在 HSV 上稳定。

1
hsv = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2HSV)
2
mask = cv2.inRange(hsv, (35, 50, 50), (85, 255, 255))

检查方式#

显示图像时确认肤色、天空、红绿区域是否正常。
打印 shape，确认灰度和彩色图维度不同。
保存中间结果，避免只看最终模型输出。

实战复盘#

复用《OpenCV 颜色空间转换》时，我会先用三到五张图片跑通流程，再扩大到完整数据集。小样本阶段要故意覆盖正常图、边界图和可能失败的图，而不是只选最干净的样本。

后续如果要写成更完整教程，可以补充输入目录结构、输出目录结构和一张可视化样例，让读者能直接对照自己的项目。

最小验收样例#

验收《OpenCV 颜色空间转换》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

颜色空间错误不会让代码崩，但会让结果悄悄变差。读图、显示、训练之间要明确 BGR 和 RGB 的转换位置。

OpenCV 读取图片检查

Sat, 30 May 2026 00:00:00 GMT

OpenCV 读取图片检查#

OpenCV 读取图片失败时，cv2.imread 不一定抛异常，它可能直接返回 None。如果后面立刻访问 img.shape，才会看到真正的报错。

所以读图后的第一件事应该是检查是否为空，而不是直接进入处理流程。

最小读图检查#

1
from pathlib import Path
2
import cv2
3

4
image_path = Path("images/demo.jpg")
5
img = cv2.imread(str(image_path))
6

7
if img is None:
8
    raise FileNotFoundError(f"failed to read image: {image_path.resolve()}")
9

10
print(img.shape, img.dtype)

shape 一般是 (height, width, channels)，OpenCV 默认按 BGR 通道读取彩色图。

常见失败原因#

路径写错，尤其是相对路径相对于当前运行目录，不是脚本所在目录。
文件名大小写不一致，Linux 区分大小写。
图片损坏或扩展名和真实格式不一致。
中文路径在某些环境下读取异常，需要先用简单英文路径排查。

批量读取时要记录失败文件#

1
bad = []
2
for p in Path("images").glob("*.jpg"):
3
    img = cv2.imread(str(p))
4
    if img is None:
5
        bad.append(str(p))
6

7
print("bad files", len(bad))
8
print(bad[:10])

读图后再谈处理#

很多视觉任务训练失败，根源是有一批图片根本没读进来。先确认图片数量、尺寸范围和通道，再进入增强、标注和模型训练。

实战复盘#

把《OpenCV 读取图片检查》用于真实视觉项目时，我会先做可视化抽查。图像任务里很多错误不会抛异常，例如颜色通道反了、检测框偏移、标签和图片不同步，但一张可视化结果就能暴露。

如果文章涉及批量处理，还要记录成功数量、失败数量和失败样本路径。视觉项目的数据量一大，没有失败清单就很难复查。

最小验收样例#

验收《OpenCV 读取图片检查》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

OpenCV 读图检查要简单直接：路径是否存在、返回是否 None、尺寸和通道是否符合预期。读图不稳，后面都不稳。

单调栈模板整理

Fri, 29 May 2026 00:00:00 GMT

单调栈模板整理#

单调栈适合解决“离当前位置最近的更大或更小元素”这类问题。它的重点不是背模板，而是理解栈里为什么只保留一部分候选元素。

我习惯从三个问题判断：要找左边还是右边，要找更大还是更小，结果是距离、下标还是数值。

题型识别#

看到“下一个更大元素”“左侧第一个更小元素”“柱状图最大矩形”“每日温度等待天数”这类描述，就可以先考虑单调栈。

如果每个元素都要和左右一串元素比较，暴力是 O(n^2)，而单调栈能把每个元素入栈出栈各一次，降到 O(n)。

维护规则#

以寻找左侧最近更小元素为例，栈内保持从栈底到栈顶递增。当前元素 x 来时，所有大于等于 x 的元素都不可能再成为后面元素的最近更小值，所以弹出。

1
def prev_less(nums):
2
    stack = []  # 存下标，nums[stack] 单调递增
3
    ans = [-1] * len(nums)
4

5
    for i, x in enumerate(nums):
6
        while stack and nums[stack[-1]] >= x:
7
            stack.pop()
8
        if stack:
9
            ans[i] = stack[-1]
10
        stack.append(i)
11

12
    return ans

怎么改成其他题#

找更大：把比较方向改成 <= 或 <。
找右侧：从右往左遍历，或在弹栈时结算被弹元素。
要距离：用当前下标减答案下标。
要数值：最后用下标回到原数组取值。

边界检查#

重复元素是单调栈里最容易出错的边界。比较时用 < 还是 <=，决定了相等元素能不能共存。题目如果要求“严格更小”，通常弹出 >=；如果允许“小于等于”，规则就要调整。

实战复盘#

学《单调栈模板整理》时，我会用三类样例验收：普通样例验证流程，边界样例验证空数组和单元素，重复样例验证相等元素的处理。只跑一个正向样例，很容易把比较符号写错还不自知。

算法文章还要写清复杂度来源。单调栈看起来有 while 循环，但每个元素最多入栈一次、出栈一次，所以总复杂度是 O(n)。这个解释比单独写一个结论更重要。

后续刷题时，可以先把题目翻译成“找左侧/右侧的更大/更小元素”。能完成这一步，模板才真正变成自己的工具。

最小验收样例#

验收《单调栈模板整理》时，我会把代码跑在递增、递减、重复元素和空输入上。单调栈尤其要看重复元素，因为比较符号的选择会直接影响答案。

如果能把每一步栈内元素画出来，就说明自己理解了维护规则；如果只能背代码，换一个方向或比较关系就很容易写错。

小结#

单调栈的核心是让栈里只保留未来仍有可能成为答案的元素。先想清比较关系和遍历方向，再写模板。

pandas 分析报告流程

Thu, 28 May 2026 00:00:00 GMT

pandas 分析报告流程#

一份数据分析报告不是几张图和几行结论的拼接，而是一条从原始数据到结论的可复查链路。

我写 pandas 分析报告时，会把读取、检查、清洗、分析、导出和结论分开，避免结果无法复现。

流程拆解#

读取数据：记录文件来源、编码和行列数。
数据检查：字段类型、缺失值、重复值、异常值。
清洗转换：保留清洗规则和前后数量对比。
指标计算：明确分组口径和统计公式。
导出结果：汇总表、明细表、异常记录分 sheet 输出。
写结论：只写数据能支撑的判断。

脚本结构#

1
def load_data(path):
2
    return pd.read_csv(path, encoding="utf-8-sig")
3

4
def check_data(df):
5
    print(df.shape)
6
    print(df.dtypes)
7
    print(df.isna().sum())
8

9
def build_report(df):
10
    summary = df.groupby("category")["amount"].sum().reset_index()
11
    return summary

报告里应该保留的证据#

原始数据行数和清洗后行数。
关键字段缺失率。
异常值处理规则。
指标口径说明。
结论对应的表格或图。

避免过度包装#

报告不需要把所有中间过程都展示给读者，但脚本里要能复现。展示层简洁，计算层透明，是我认为比较稳的做法。

实战复盘#

复用《pandas 分析报告流程》时，不要只复制代码块。先把自己的字段名、数据口径和异常规则写出来，再替换示例里的列名。pandas 的函数很通用，但业务字段的含义不能自动迁移。

每次处理完成后，我会抽样看几条原始记录和处理后记录。尤其是日期、金额、分类字段，机器统计和肉眼抽查要一起做，才能发现格式看似正常但含义错位的问题。

这类文章后续可以继续补充真实小表格作为输入示例。输入、处理、输出三者都出现，教程才不会变成只解释 API。

最小验收样例#

验收《pandas 分析报告流程》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

pandas 报告的质量来自可复查。结论越明确，越要能追溯到清洗规则和统计口径。

pandas 缺失值填充策略

Wed, 27 May 2026 00:00:00 GMT

pandas 缺失值填充策略#

缺失值处理不能一律填 0。不同字段的缺失含义不同：金额缺失、分类缺失、日期缺失、文本缺失，处理方式都应该不同。

填充前先问：这个缺失是未知、没有发生，还是数据采集失败？

先统计缺失#

1
missing = df.isna().mean().sort_values(ascending=False)
2
print((missing * 100).round(2).head(20))

缺失率高的字段要重点判断是否还能用于分析。缺失率很低的字段，也要看缺失是否集中在某个类别或时间段。

常见填充策略#

数值字段：可填 0、中位数、均值，或保留缺失，取决于业务含义。
分类字段：可以填 unknown，但要避免把未知当成真实类别。
日期字段：通常不建议随意填充，除非有明确规则。
文本字段：可填空字符串，但分析时要区分空文本和缺失。

示例#

1
df["amount"] = df["amount"].fillna(0)
2
df["city"] = df["city"].fillna("unknown")
3
df["age"] = df["age"].fillna(df["age"].median())

填充后要留痕#

重要字段填充前可以先创建标记列，记录哪些值原本缺失。这样后续模型或分析能知道哪些数据是补出来的。

1
df["amount_was_missing"] = df["amount"].isna()
2
df["amount"] = df["amount"].fillna(0)

实战复盘#

写《pandas 缺失值填充策略》这类数据分析文章时，我会强制保留“检查点”。因为数据分析里最危险的不是报错，而是代码顺利跑完却得到错误结论。

一个合格的 pandas 步骤，至少要能回答：输入多少行、输出多少行、哪些字段被修改、失败值有多少、是否有样本可以人工复核。缺少这些信息，代码就很难进入正式流程。

如果以后把这些文章串成系列，可以按读取、检查、清洗、变换、统计、导出排列。这样读者能从原始数据一路走到可交付结果。

最小验收样例#

验收《pandas 缺失值填充策略》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

缺失值填充是业务判断，不是格式清洗。先理解缺失含义，再选择填法，并尽量保留可追溯标记。

pandas 交叉表统计

Tue, 26 May 2026 00:00:00 GMT

pandas 交叉表统计#

交叉表适合回答两个分类变量之间的分布问题。例如不同城市的用户等级、不同模型的预测结果、不同渠道的转化状态。

它比单列 value_counts 更进一步，能看到组合关系。

基础交叉表#

1
table = pd.crosstab(df["city"], df["level"])
2
print(table)

行是城市，列是等级，单元格是数量。这个结果很适合快速看分布是否偏斜。

加比例#

1
row_ratio = pd.crosstab(df["city"], df["level"], normalize="index")
2
print((row_ratio * 100).round(2))

normalize="index" 表示每一行内部算比例，适合比较不同城市内的等级结构。

加合计#

1
table = pd.crosstab(
2
    df["city"],
3
    df["level"],
4
    margins=True,
5
    margins_name="total",
6
)

使用前清洗类别#

交叉表对类别值非常敏感。空格、大小写、缺失值都会让结果多出奇怪的行列。统计前最好先做字符串清洗，并决定缺失值是否单独作为一类。

实战复盘#

写《pandas 交叉表统计》这类数据分析文章时，我会强制保留“检查点”。因为数据分析里最危险的不是报错，而是代码顺利跑完却得到错误结论。

如果以后把这些文章串成系列，可以按读取、检查、清洗、变换、统计、导出排列。这样读者能从原始数据一路走到可交付结果。

最小验收样例#

验收《pandas 交叉表统计》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

crosstab 是观察分类变量关系的快速工具。数量和比例一起看，才能避免被样本规模误导。

pandas rolling 滑动窗口

Mon, 25 May 2026 00:00:00 GMT

pandas rolling 滑动窗口#

滑动窗口常用于平滑波动、计算移动平均、观察趋势。它不是简单地多算几行，而是在每个时间点回看前一段数据。

使用 rolling 前，要先确认数据已经按时间排序，并且时间粒度符合分析目标。

固定行数窗口#

1
df = df.sort_values("date")
2
df["ma7"] = df["value"].rolling(window=7, min_periods=1).mean()
3
df["sum7"] = df["value"].rolling(window=7, min_periods=1).sum()

window=7 表示最近 7 行，不一定是最近 7 天。如果数据缺日期或一天多条记录，要特别小心。

基于时间窗口#

1
ts = df.sort_values("date").set_index("date")
2
ts["ma7d"] = ts["value"].rolling("7D", min_periods=1).mean()

时间窗口要求索引是 datetime。它更适合不规则时间间隔的数据。

分组滑动窗口#

1
df["user_ma3"] = (
2
    df.sort_values("date")
3
      .groupby("user_id")["value"]
4
      .transform(lambda s: s.rolling(3, min_periods=1).mean())
5
)

检查点#

是否按时间排序。
窗口是按行还是按时间。
前几行不足窗口时如何处理。
是否发生了不同用户或类别之间的数据串联。

实战复盘#

写《pandas rolling 滑动窗口》这类数据分析文章时，我会强制保留“检查点”。因为数据分析里最危险的不是报错，而是代码顺利跑完却得到错误结论。

如果以后把这些文章串成系列，可以按读取、检查、清洗、变换、统计、导出排列。这样读者能从原始数据一路走到可交付结果。

最小验收样例#

验收《pandas rolling 滑动窗口》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

rolling 的关键是明确窗口含义。窗口按行还是按时间、是否分组，会直接改变结果解释。

pandas 抽样检查数据

Sun, 24 May 2026 00:00:00 GMT

pandas 抽样检查数据#

很多人检查数据只看 head()，但前几行往往不能代表全表。排序后的数据、按时间追加的数据、分组导出的数据，都可能让前几行非常单一。

抽样检查的目标是从不同位置、不同类别里看到真实数据形态。

随机抽样#

1
sample = df.sample(n=20, random_state=42)
2
print(sample)

random_state 可以让抽样结果可复现。排查问题时，能复现很重要。

按类别抽样#

如果数据有类别字段，只做全局随机抽样可能抽不到少数类。可以按组抽样，每个类别取几条。

1
sample_by_class = (
2
    df.groupby("category", group_keys=False)
3
      .apply(lambda x: x.sample(min(len(x), 3), random_state=42))
4
)
5
print(sample_by_class)

抽样看什么#

字段格式是否统一。
文本是否有空格、乱码、异常符号。
数值范围是否符合常识。
日期是否跨越预期时间段。
少数类别是否存在特殊格式。

抽样不能替代统计#

抽样适合发现样子不对的数据，但不能证明数据没有问题。抽样后仍然要配合缺失率、唯一值数量、分位数等统计指标。

实战复盘#

写《pandas 抽样检查数据》这类数据分析文章时，我会强制保留“检查点”。因为数据分析里最危险的不是报错，而是代码顺利跑完却得到错误结论。

如果以后把这些文章串成系列，可以按读取、检查、清洗、变换、统计、导出排列。这样读者能从原始数据一路走到可交付结果。

最小验收样例#

验收《pandas 抽样检查数据》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

抽样检查是数据分析的肉眼校验环节。不要只看前几行，要让样本覆盖不同类别和不同位置。

pandas 导出 Excel 笔记

Sat, 23 May 2026 00:00:00 GMT

pandas 导出 Excel 笔记#

数据分析的最后一步经常是把结果交给别人看。Excel 仍然是最常见的交付格式，所以导出时不能只保证文件生成，还要保证别人打开后能读懂。

我导出 Excel 时会同时考虑 sheet 结构、字段顺序、索引和基础格式。

基础导出#

1
result.to_excel("result.xlsx", index=False)

index=False 很重要。除非索引本身有业务含义，否则导出默认索引会让文件多一列无意义数字。

多 sheet 文件#

1
with pd.ExcelWriter("report.xlsx", engine="openpyxl") as writer:
2
    summary.to_excel(writer, sheet_name="summary", index=False)
3
    detail.to_excel(writer, sheet_name="detail", index=False)
4
    errors.to_excel(writer, sheet_name="errors", index=False)

我喜欢把汇总、明细和异常记录分成不同 sheet。这样读者先看结论，需要追溯时再看明细。

导出前整理列#

导出前最好手动指定列顺序，不要依赖 DataFrame 当前顺序。

1
cols = ["order_id", "user_id", "order_date", "amount", "status"]
2
detail = detail[cols].sort_values("order_date")

导出后复核#

文件是否能正常打开。
行数是否和 DataFrame 一致。
日期、金额格式是否可读。
中文 sheet 名是否正常。
是否把临时列、调试列一起导出。

实战复盘#

复用《pandas 导出 Excel 笔记》时，不要只复制代码块。先把自己的字段名、数据口径和异常规则写出来，再替换示例里的列名。pandas 的函数很通用，但业务字段的含义不能自动迁移。

这类文章后续可以继续补充真实小表格作为输入示例。输入、处理、输出三者都出现，教程才不会变成只解释 API。

最小验收样例#

验收《pandas 导出 Excel 笔记》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

Excel 导出是分析结果的交付环节。结构清楚、字段干净、可复核，比单纯生成文件更重要。

pandas 字符串清洗

Fri, 22 May 2026 00:00:00 GMT

pandas 字符串清洗#

很多表格问题都藏在字符串里：前后空格、全角符号、大小写不一致、手机号带短横线、金额带单位。肉眼看起来差不多，程序匹配时却完全不同。

字符串清洗要尽量显式记录规则，避免把数据改得不可追溯。

先统一基本格式#

1
s = df["name"].astype("string")
2
df["name_clean"] = (
3
    s.str.strip()
4
     .str.replace("　", " ", regex=False)
5
     .str.replace(r"\s+", " ", regex=True)
6
)

这里同时处理普通空格和全角空格，再把连续空白合并成一个空格。

提取结构化信息#

1
df["phone_digits"] = df["phone"].astype("string").str.replace(r"\D", "", regex=True)
2
df["province"] = df["address"].astype("string").str.extract(r"^(.*?省)")

提取字段前先确认样本格式，不要只用一条记录写正则。

替换和映射#

对于少量明确的同义值，可以用字典映射，比写一堆 if 更清楚。

1
mapping = {"男": "M", "男性": "M", "女": "F", "女性": "F"}
2
df["gender_clean"] = df["gender"].astype("string").str.strip().map(mapping)

清洗后检查#

原始列不要立刻删除，保留对照。
统计清洗前后类别数量。
抽样查看被替换的记录。
对无法解析的值单独导出检查。

实战复盘#

把《pandas 字符串清洗》放到真实数据分析里，我会先准备一份最小样例和一份异常样例。最小样例验证代码路径是否通，异常样例验证缺失值、重复值、类型错误或边界值是否被发现。

pandas 文章最重要的证据不是代码能运行，而是运行后打印出来的 shape、dtypes、缺失率、前几行样本和关键统计是否符合预期。这些输出应该保留在分析记录里。

如果这一步会影响后续报表或模型，我会把清洗前后的行数、字段数量和异常记录数量写清楚。这样以后结果变化时，能追溯到底是哪一步改变了数据。

最小验收样例#

验收《pandas 字符串清洗》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

字符串清洗不是把文本变整齐这么简单，而是把不可控输入变成可分析字段。规则越明确，后续越容易复查。

pandas 分类字段统计

Thu, 21 May 2026 00:00:00 GMT

pandas 分类字段统计#

分类字段统计是理解数据分布最快的方法。一个 value_counts 就能看到类别是否集中、是否有拼写问题、是否存在空值。

但在统计前要先清洗文本，否则“北京”“北京 ”和“beijing”可能被当成三个类别。

基础统计#

1
counts = df["city"].value_counts(dropna=False)
2
ratio = df["city"].value_counts(normalize=True, dropna=False)
3
print(counts.head(20))
4
print((ratio * 100).round(2).head(20))

dropna=False 可以把缺失值也统计出来，适合数据质量检查。

统计前清洗#

1
df["city_clean"] = (
2
    df["city"]
3
    .astype("string")
4
    .str.strip()
5
    .str.replace("市", "", regex=False)
6
)
7
print(df["city_clean"].value_counts(dropna=False).head(20))

具体替换规则要根据业务来，不要为了合并类别而把真实差异抹掉。

多字段分类#

1
summary = (
2
    df.groupby(["city_clean", "level"], dropna=False)
3
      .size()
4
      .reset_index(name="count")
5
      .sort_values("count", ascending=False)
6
)
7
print(summary.head(20))

怎么看结果#

是否有明显的空值或未知类别。
是否有同义类别被拆开。
头部类别是否过度集中。
长尾类别是否需要合并为“其他”。

实战复盘#

复用《pandas 分类字段统计》时，不要只复制代码块。先把自己的字段名、数据口径和异常规则写出来，再替换示例里的列名。pandas 的函数很通用，但业务字段的含义不能自动迁移。

这类文章后续可以继续补充真实小表格作为输入示例。输入、处理、输出三者都出现，教程才不会变成只解释 API。

最小验收样例#

验收《pandas 分类字段统计》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

分类统计看似简单，但它往往最早暴露数据质量问题。先清洗再统计，结果才有解释价值。

pandas 异常值检查

Wed, 20 May 2026 00:00:00 GMT

pandas 异常值检查#

异常值不一定是脏数据。一个特别大的订单金额可能是录入错误，也可能是真实的大客户。检查异常值的目的不是自动删除，而是把需要确认的记录找出来。

我通常会结合统计分布、业务范围和原始记录来判断。

先做描述统计#

1
print(df["amount"].describe(percentiles=[0.01, 0.05, 0.95, 0.99]))
2
print(df.nlargest(10, "amount")[["order_id", "amount", "user_id"]])

最大值、99 分位数和均值之间差距很大时，就要进一步看极端记录。

IQR 方法#

1
q1 = df["amount"].quantile(0.25)
2
q3 = df["amount"].quantile(0.75)
3
iqr = q3 - q1
4
low = q1 - 1.5 * iqr
5
high = q3 + 1.5 * iqr
6
outliers = df[(df["amount"] < low) | (df["amount"] > high)]
7
print(outliers.head())

IQR 适合快速筛选，但不能替代业务判断。不同业务的正常范围差异很大。

业务规则更重要#

比如年龄小于 0 或大于 120 基本是错误；订单金额为负可能是退款；图片宽高为 0 一定要排查数据读取。

异常值处理要记录原因：删除、截断、单独分析，还是保留。

处理前后对比#

异常值数量占比。
删除后样本量变化。
关键指标是否大幅变化。
被处理的记录能否追溯到原始 ID。

实战复盘#

复用《pandas 异常值检查》时，不要只复制代码块。先把自己的字段名、数据口径和异常规则写出来，再替换示例里的列名。pandas 的函数很通用，但业务字段的含义不能自动迁移。

这类文章后续可以继续补充真实小表格作为输入示例。输入、处理、输出三者都出现，教程才不会变成只解释 API。

最小验收样例#

验收《pandas 异常值检查》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

异常值检查的核心是发现和解释，而不是一键删除。统计方法负责筛出来，业务判断负责决定怎么处理。

pandas apply 与向量化

Tue, 19 May 2026 00:00:00 GMT

pandas apply 与向量化#

apply 很好用，但不应该成为处理每一列的默认方式。pandas 的优势在于向量化操作，能用内置字符串、数值、日期方法时，通常比逐行 apply 更快、更清晰。

我的原则是：先找向量化写法，找不到再考虑 apply。

向量化优先#

1
df["name"] = df["name"].str.strip()
2
df["amount"] = pd.to_numeric(df["amount"], errors="coerce")
3
df["is_large"] = df["amount"] >= 1000

这些操作不需要逐行函数，pandas 已经提供了专门的方法。

apply 适合什么场景#

当逻辑确实依赖多列组合，且向量化表达过于绕时，可以用 apply(axis=1)。但要意识到它通常更慢，数据量大时需要重新设计。

1
def label(row):
2
    if row["amount"] >= 1000 and row["vip"] == 1:
3
        return "high_value"
4
    return "normal"
5

6
df["label"] = df.apply(label, axis=1)

可以替代 apply 的写法#

1
import numpy as np
2

3
df["label"] = np.where(
4
    (df["amount"] >= 1000) & (df["vip"] == 1),
5
    "high_value",
6
    "normal",
7
)

条件分支简单时，np.where 或 np.select 更适合。

判断标准#

数据量很小，以可读性为主，可以接受 apply。
数据量很大，优先向量化或分块处理。
逻辑涉及外部 API 或文件 IO，不适合直接在 apply 里跑。
写完后用小样本手动验证几行结果。

实战复盘#

写《pandas apply 与向量化》这类数据分析文章时，我会强制保留“检查点”。因为数据分析里最危险的不是报错，而是代码顺利跑完却得到错误结论。

如果以后把这些文章串成系列，可以按读取、检查、清洗、变换、统计、导出排列。这样读者能从原始数据一路走到可交付结果。

最小验收样例#

验收《pandas apply 与向量化》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

apply 不是不能用，而是要知道它的成本。能向量化就向量化，复杂业务逻辑再用 apply 保持清晰。

pandas 排序和排名

Mon, 18 May 2026 00:00:00 GMT

pandas 排序和排名#

排序和排名经常用于找 Top N、生成榜单、筛选异常值。看起来简单，但升降序、并列名次和分组排名都需要明确规则。

如果规则没说清楚，同一份数据可能排出不同结果。

基础排序#

1
top = df.sort_values(
2
    by=["score", "created_at"],
3
    ascending=[False, True],
4
)
5
print(top.head(10))

多字段排序时，要明确每个字段的升降序。比如分数越高越靠前，时间越早越靠前。

排名方法#

1
df["rank_min"] = df["score"].rank(method="min", ascending=False)
2
df["rank_dense"] = df["score"].rank(method="dense", ascending=False)
3
df["rank_first"] = df["score"].rank(method="first", ascending=False)

min 会让并列项占用名次，dense 不跳号，first 按出现顺序打破并列。榜单规则不同，选择也不同。

分组内排名#

1
df["rank_in_class"] = (
2
    df.groupby("class")["score"]
3
      .rank(method="dense", ascending=False)
4
)
5
top3 = df[df["rank_in_class"] <= 3]

容易出错的点#

数值列被读成字符串，100 可能排在 20 前后不符合预期。
没有说明并列分数怎么处理。
排序后忘记重置索引，展示时看起来顺序混乱。
Top N 是全局 Top N，还是每组 Top N，没有定义清楚。

实战复盘#

复用《pandas 排序和排名》时，不要只复制代码块。先把自己的字段名、数据口径和异常规则写出来，再替换示例里的列名。pandas 的函数很通用，但业务字段的含义不能自动迁移。

这类文章后续可以继续补充真实小表格作为输入示例。输入、处理、输出三者都出现，教程才不会变成只解释 API。

最小验收样例#

验收《pandas 排序和排名》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

排序和排名要先写清规则，再写代码。特别是并列名次和分组排名，不能靠默认参数碰运气。

pandas 透视表基础

Sun, 17 May 2026 00:00:00 GMT

pandas 透视表基础#

透视表适合把明细数据整理成二维汇总结果。比如按月份和分类统计销售额、按班级和性别统计人数、按模型和数据集比较指标。

它的价值是把 groupby、聚合和 reshape 合在一起，让结果更接近报表形态。

最小示例#

1
table = pd.pivot_table(
2
    df,
3
    index="month",
4
    columns="category",
5
    values="amount",
6
    aggfunc="sum",
7
    fill_value=0,
8
    margins=True,
9
)
10
print(table)

index 是行维度，columns 是列维度，values 是被统计的数值字段，aggfunc 决定怎么算。

什么时候比 groupby 更方便#

如果结果需要给人阅读，透视表更直观；如果后续还要继续链式处理，groupby 可能更灵活。两者不是替代关系，而是输出形态不同。

多指标统计#

1
table = pd.pivot_table(
2
    df,
3
    index="category",
4
    values=["amount", "quantity"],
5
    aggfunc={"amount": "sum", "quantity": "mean"},
6
)
7
print(table)

检查结果#

汇总总额是否和原表一致。
空值是否应该填 0，还是保留缺失。
分类数量是否异常变多，可能存在空格或大小写问题。
margins=True 的合计是否符合业务口径。

实战复盘#

复用《pandas 透视表基础》时，不要只复制代码块。先把自己的字段名、数据口径和异常规则写出来，再替换示例里的列名。pandas 的函数很通用，但业务字段的含义不能自动迁移。

这类文章后续可以继续补充真实小表格作为输入示例。输入、处理、输出三者都出现，教程才不会变成只解释 API。

最小验收样例#

验收《pandas 透视表基础》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

透视表适合把明细表变成可读报表。写之前先想清楚行维度、列维度、指标和聚合方式，结果会稳定很多。

pandas merge 左连接笔记

Sat, 16 May 2026 00:00:00 GMT

pandas merge 左连接笔记#

左连接是数据分析里最常用的合并方式：以左表为主，把右表的补充字段拼进来。但它也最容易因为重复键导致行数膨胀。

我的习惯是每次 merge 前后都检查行数、键唯一性和未匹配数量。

什么时候用 left join#

当左表是分析主体时使用左连接。例如订单表是主体，用户表只是补充用户等级；图片清单是主体，标注表只是补充类别信息。

左连接应该保证左表记录不丢失，但不保证行数一定不变。如果右表同一个键有多行，行数会被放大。

合并前检查键#

1
print(orders["user_id"].isna().sum())
2
print(users["user_id"].duplicated().sum())
3
print(users[users["user_id"].duplicated(keep=False)].head())

如果右表键不唯一，要先决定聚合、去重，还是允许一对多合并。

带指示列合并#

1
merged = orders.merge(
2
    users[["user_id", "level"]],
3
    on="user_id",
4
    how="left",
5
    indicator=True,
6
)
7

8
print(orders.shape, merged.shape)
9
print(merged["_merge"].value_counts())

indicator=True 会生成 _merge，可以快速看到哪些左表记录没有匹配到右表。

常见问题#

两个表的键类型不同，一个是数字，一个是字符串。
键里有前后空格，肉眼看一样但实际匹配不上。
右表重复键导致合并后行数变多。
合并后同名列出现 _x、_y，说明字段设计需要整理。

实战复盘#

写《pandas merge 左连接笔记》这类数据分析文章时，我会强制保留“检查点”。因为数据分析里最危险的不是报错，而是代码顺利跑完却得到错误结论。

如果以后把这些文章串成系列，可以按读取、检查、清洗、变换、统计、导出排列。这样读者能从原始数据一路走到可交付结果。

最小验收样例#

验收《pandas merge 左连接笔记》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

merge 的风险不在语法，而在数据关系。每次左连接都要确认键、行数和未匹配记录。

pandas 日期列解析

Fri, 15 May 2026 00:00:00 GMT

pandas 日期列解析#

日期列是很多分析的时间轴。只要日期解析错，按月统计、时间筛选、滑动窗口都会跟着错。

实际数据里常见的问题包括格式混用、空字符串、Excel 序列号、中文日期和时区信息。我的做法是先解析，再统计失败样本。

基础解析#

1
df["date"] = pd.to_datetime(df["date"], errors="coerce")
2
print(df["date"].isna().sum())
3
print(df.loc[df["date"].isna(), "date"].head())

errors="coerce" 适合排查，因为它不会让程序直接中断，而是把失败值变成 NaT。但后面必须检查失败数量。

格式混用时怎么处理#

如果一列里同时有 2026-05-15、2026/5/15、2026年5月15日，可以先统一替换中文字符和分隔符，再解析。

1
s = (
2
    df["date"].astype(str)
3
    .str.strip()
4
    .str.replace("年", "-", regex=False)
5
    .str.replace("月", "-", regex=False)
6
    .str.replace("日", "", regex=False)
7
)
8
df["date"] = pd.to_datetime(s, errors="coerce")

按时间分析前的检查#

最小日期和最大日期是否合理。
是否出现大量未来日期或 1970 年。
时间列是否有重复或缺失。
是否需要先设置为索引再 resample。

按月统计示例#

1
monthly = (
2
    df.dropna(subset=["date"])
3
      .set_index("date")
4
      .resample("ME")["amount"]
5
      .sum()
6
)
7
print(monthly.tail())

实战复盘#

复用《pandas 日期列解析》时，不要只复制代码块。先把自己的字段名、数据口径和异常规则写出来，再替换示例里的列名。pandas 的函数很通用，但业务字段的含义不能自动迁移。

这类文章后续可以继续补充真实小表格作为输入示例。输入、处理、输出三者都出现，教程才不会变成只解释 API。

最小验收样例#

验收《pandas 日期列解析》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

日期列解析要先暴露失败值，再做时间统计。不要让 NaT 和错误年份悄悄进入分析结果。

pandas 重复数据处理

Thu, 14 May 2026 00:00:00 GMT

pandas 重复数据处理#

重复数据不能简单理解为整行完全一样。有时订单号重复才是问题，有时同一个用户多条记录是正常行为。

处理重复值前，必须先定义什么叫重复，以及重复后应该保留哪一条。

先确认重复规则#

如果业务主键是 order_id，就按订单号判断；如果分析的是用户画像，可能要按 user_id 保留最新一条；如果是日志数据，时间戳不同的多条记录可能都要保留。

1
key = ["order_id"]
2
dup = df[df.duplicated(subset=key, keep=False)].sort_values(key)
3
print(dup.head(20))

选择保留策略#

keep="first" 保留第一次出现，keep="last" 保留最后一次出现，keep=False 可以把所有重复记录都标出来。

如果要保留最新记录，先按时间排序，再删除重复。

1
df = df.sort_values("updated_at")
2
clean = df.drop_duplicates(subset=["order_id"], keep="last")

删除前后都要对账#

删除重复数据前先统计数量，删除后确认行数变化符合预期。不要在没有备份的原表上直接覆盖。

1
before = len(df)
2
clean = df.drop_duplicates(subset=["order_id"], keep="last")
3
print("removed", before - len(clean))
4
print(clean["order_id"].duplicated().sum())

常见误区#

不指定 subset，导致本该按主键去重的任务变成整行去重。
没有排序就使用 keep="last"，保留的并不一定是最新记录。
把正常的多次购买、多次登录误删成一条。

实战复盘#

把《pandas 重复数据处理》放到真实数据分析里，我会先准备一份最小样例和一份异常样例。最小样例验证代码路径是否通，异常样例验证缺失值、重复值、类型错误或边界值是否被发现。

最小验收样例#

验收《pandas 重复数据处理》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

去重不是一个函数调用，而是一次业务判断。先定义重复，再选择保留策略，最后用数量变化验证结果。

pandas 字段类型检查

Wed, 13 May 2026 00:00:00 GMT

pandas 字段类型检查#

很多 pandas 分析结果不对，并不是算法错了，而是字段类型从一开始就错了。金额被读成字符串、日期没有解析、编号被当成数字，都会在后续统计中制造隐蔽问题。

我习惯在读入数据后立即检查字段类型，把它当成数据分析的第一道质量门。

先看整体类型#

1
import pandas as pd
2

3
df = pd.read_csv("orders.csv")
4
print(df.shape)
5
print(df.dtypes)
6
print(df.head(3).T)

head().T 很适合列很多的表格，可以快速看到每个字段的样子。只看 dtypes 有时不够，因为 object 可能是文本、混合数字，也可能是脏数据。

常见需要转换的字段#

日期字段：使用 pd.to_datetime，并设置 errors="coerce" 找出失败值。
金额字段：先去掉逗号、货币符号，再转数值。
分类字段：确认是否有大小写、空格和同义写法。
编号字段：学号、订单号、手机号通常应该保留字符串。

转换示例#

1
df["order_date"] = pd.to_datetime(df["order_date"], errors="coerce")
2
df["amount"] = (
3
    df["amount"]
4
    .astype(str)
5
    .str.replace(",", "", regex=False)
6
    .pipe(pd.to_numeric, errors="coerce")
7
)
8

9
print(df[["order_date", "amount"]].isna().sum())

不要忽略异常转换#

转换后一定要看失败数量。errors="coerce" 会把解析失败的值变成缺失值，如果不检查，就会把数据质量问题悄悄吞掉。

实战复盘#

复用《pandas 字段类型检查》时，不要只复制代码块。先把自己的字段名、数据口径和异常规则写出来，再替换示例里的列名。pandas 的函数很通用，但业务字段的含义不能自动迁移。

这类文章后续可以继续补充真实小表格作为输入示例。输入、处理、输出三者都出现，教程才不会变成只解释 API。

最小验收样例#

验收《pandas 字段类型检查》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

字段类型决定了后续能做什么分析。先检查类型，再写统计逻辑，能少掉很多看似奇怪的结果。

pandas 读取 CSV 编码问题

Tue, 12 May 2026 00:00:00 GMT

pandas 读取 CSV 编码问题#

CSV 看起来是最简单的数据格式，但实际项目里经常因为编码、分隔符或表头问题让第一步就卡住。特别是中文表格，从 Excel、网页、系统后台导出后，编码并不总是 UTF-8。

排查读取问题时，不要一上来就改业务逻辑。先把文件读对，再谈清洗和分析。

先判断编码#

如果中文变成乱码，优先尝试 utf-8-sig 和 gbk。utf-8-sig 常见于带 BOM 的 CSV，gbk 常见于 Windows 环境导出的中文文件。

1
import pandas as pd
2

3
for enc in ["utf-8", "utf-8-sig", "gbk", "gb18030"]:
4
    try:
5
        df = pd.read_csv("data.csv", encoding=enc, nrows=5)
6
        print(enc, df.head())
7
        break
8
    except UnicodeDecodeError as e:
9
        print(enc, "failed", e)

再检查分隔符#

有些文件扩展名叫 .csv，实际却用制表符、分号或多个空格分隔。读取后如果只有一列，或者列名挤在一起，就要检查 sep。

1
df = pd.read_csv("data.csv", encoding="gbk", sep=None, engine="python")
2
print(df.shape)
3
print(df.columns.tolist())

最后看空值和表头#

后台导出的表格常会在前几行放说明文字，真正表头不在第一行。这时可以用 skiprows 或 header 指定读取位置。

读完后立刻打印 shape、columns、head，不要等分析结果异常时再回头查输入。

复查点#

行数是否和原文件大致一致。
中文列名是否正常显示。
是否出现 Unnamed: 0 这类多余索引列。
数值列有没有被整体读成字符串。

实战复盘#

复用《pandas 读取 CSV 编码问题》时，不要只复制代码块。先把自己的字段名、数据口径和异常规则写出来，再替换示例里的列名。pandas 的函数很通用，但业务字段的含义不能自动迁移。

这类文章后续可以继续补充真实小表格作为输入示例。输入、处理、输出三者都出现，教程才不会变成只解释 API。

最小验收样例#

验收《pandas 读取 CSV 编码问题》时，我会手写一个三到五行的小 DataFrame：一行正常数据，一行缺失或异常数据，一行边界数据。先让示例在小表上跑通，再换成完整数据集。

小表的好处是结果可以人工计算。只要人工结果和 pandas 输出对不上，就说明代码逻辑或字段口径还没想清楚。这个过程比直接在大表上调试更可靠。

小结#

CSV 读取问题要按编码、分隔符、表头、空值的顺序排查。第一步读错，后面所有统计都会跟着错。

博客修改后的发布检查

Mon, 11 May 2026 00:00:00 GMT

博客修改后的发布检查#

博客改完不代表已经上线。静态站通常需要重新构建，再把新的 dist 发布到服务器。只上传 Markdown，线上页面不会自动变化。

我发布后会重点确认三件事：构建成功、产物替换成功、线上页面真的更新。

先构建再替换#

不要在原 dist 上边删边构建。更稳妥的做法是在临时目录构建完成，确认成功后再替换线上 dist，这样失败时不会把正在访问的网站清空。

Terminal window

1
pnpm install --frozen-lockfile
2
pnpm build
3
test -f dist/index.html

替换时保留旧版本#

上线前把旧 dist 改名保存，例如 dist.prev.20260701172501。如果新版本页面异常，可以快速切回旧目录。

线上验证#

首页返回 200。
修改过的文章 URL 返回 200。
/api/allPostMeta.json 时间和数量更新。
/pagefind/pagefind.js 可访问。
Nginx 配置测试通过。

缓存问题#

如果服务器文件已经更新但浏览器仍显示旧页面，先用无痕窗口或强制刷新确认。不要急着重复部署，避免把缓存问题误判成构建失败。

实战复盘#

复盘《博客修改后的发布检查》时，我会把它当成一个站点维护动作，而不是单篇文章。凡是影响首页、分类、RSS、Sitemap、搜索索引或旧链接的改动，都要在发布后做一次线上验证。

如果只在源码里看起来正确，但线上接口或页面没有变化，就说明构建或发布链路还有问题。博客维护类内容必须把“怎么确认已经生效”写清楚。

以后继续扩展这类文章时，可以补充真实命令输出、截图前后的差异，以及回滚路径。这样文章会更接近操作手册，而不是零散备忘。

最小验收样例#

验收《博客修改后的发布检查》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

如果文章讲的是站点维护，还要记录修改前后差异：改了哪个文件、构建产物是否更新、线上 HTTP 状态码是多少。这样后面出问题时，可以直接回到这次验收记录。

小结#

发布检查要看线上事实，不看感觉。构建日志、文件时间、HTTP 状态码和页面内容都确认后，才算真正完成上线。

每日写作节奏整理

Sun, 10 May 2026 00:00:00 GMT

每日写作节奏整理#

每日写作最难的不是某一天写很多，而是保持稳定产出。对技术博客来说，稳定并不等于每天硬凑一篇，而是把平时遇到的问题及时整理成可读的文章。

我把每日写作拆成四个动作：记录问题、补足上下文、整理步骤、发布复盘。

当天记录问题#

遇到问题时先记下原始现象：报错信息、命令、输入文件、系统环境。不要等问题解决后只写结论，因为最有价值的往往是中间定位过程。

草稿只解决一个主题#

一篇日更文章不需要覆盖整个知识体系。比如今天只讲 pip 下载超时处理，就不要顺手扩展到完整 Python 环境管理。

主题越小，越容易写具体，也更适合作为以后检索的入口。

发布前做三次确认#

标题是否能独立表达问题。
正文是否有可执行步骤，而不是只有感想。
结尾是否写清楚这次经验下次如何复用。

每周回看栏目#

每天写会产生很多单点文章，每周应该回看一次分类结构，把相关主题串起来。这样博客不是流水账，而是逐步形成知识地图。

实战复盘#

复盘《每日写作节奏整理》时，我会把它当成一个站点维护动作，而不是单篇文章。凡是影响首页、分类、RSS、Sitemap、搜索索引或旧链接的改动，都要在发布后做一次线上验证。

如果只在源码里看起来正确，但线上接口或页面没有变化，就说明构建或发布链路还有问题。博客维护类内容必须把“怎么确认已经生效”写清楚。

以后继续扩展这类文章时，可以补充真实命令输出、截图前后的差异，以及回滚路径。这样文章会更接近操作手册，而不是零散备忘。

最小验收样例#

验收《每日写作节奏整理》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

每日写作的核心是把真实问题及时沉淀。少写空泛总结，多保留场景和步骤，长期看才会变成有用的技术资料。

旧文章迁移质量检查

Sat, 09 May 2026 00:00:00 GMT

旧文章迁移质量检查#

旧文章迁移不是把 Markdown 文件复制过去就结束。新旧博客的分类、frontmatter、图片路径、URL 规则和搜索索引都可能不一样。

迁移质量的标准是：文章能打开，内容能读，图片能显示，分类能归档，搜索能找到。

内容完整性#

先对照旧文章确认标题、正文、代码块和图片是否完整。特别是代码块，迁移时很容易因为反引号缺失导致后半篇文章格式全乱。

如果旧文章只有代码，新博客里最好补上题目背景、输入输出、思路和复杂度，不要原样塞进来。

元数据重建#

旧博客可能没有 description、tags 或 category。迁移时要重新补齐，而不是全部用默认值。

创建时间原则上保留旧文章时间，除非文章已经被完全重写并且需要作为新内容发布。

链接和图片#

文章内链是否还指向旧域名。
图片路径是否能在新站访问。
旧 URL 是否需要跳转到新 URL。
分类页和归档页是否出现这篇文章。

搜索验证#

迁移后至少用标题中的两个关键词搜一次。能打开页面不代表能被搜索到，搜索索引必须在新构建产物里重新生成。

实战复盘#

我会用《旧文章迁移质量检查》建立一个可复用的维护标准：先说明为什么要做，再写具体检查项，最后给出发布后的确认方式。读者照着做时，不需要再猜下一步。

博客类文章最容易变成泛泛而谈，所以每篇都应该留下明确对象，例如 frontmatter、Pagefind、Nginx、Sitemap、分类卡片。对象越明确，文章越容易被搜索和复用。

如果以后发现文章只有原则没有操作，就应该补一个最小命令或检查清单。维护博客本身也是工程工作，要能验证、能回滚、能复盘。

最小验收样例#

验收《旧文章迁移质量检查》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

迁移文章的重点是恢复文章的使用价值，而不是只恢复文件数量。读者能顺利阅读和检索，迁移才算完成。

个人博客文章模板优化

Fri, 08 May 2026 00:00:00 GMT

个人博客文章模板优化#

文章模板的作用是降低开头成本，不是把所有文章写成同一种语气。模板如果只剩固定句式，读者会很快感觉到内容没有针对问题本身展开。

我更愿意保留结构，不复用空话。也就是每篇都可以有场景、步骤、验证和总结，但这些部分必须围绕标题重新写。

模板应该约束结构#

一个好的技术文章模板，会提醒我不要漏掉必要信息：问题现象是什么、为什么会出现、怎么定位、怎么验证结果。

但模板不应该替我写正文。如果某个段落换个标题还能直接用，那它基本就是废话。

不同栏目要有不同写法#

数据分析文章应该给出数据检查顺序和 pandas 示例。
算法文章应该讲题型识别、状态维护和边界条件。
计算机视觉文章应该强调输入图片、标注、可视化和结果复核。
问题解决文章应该写出现象、命令、日志和处理判断。

我会保留的固定部分#

固定的是检查意识，不是句子本身。比如“验证结果”这一节可以保留，但验证 pandas 缺失值和验证 Nginx 403 的方法完全不同，不能用同一段话糊过去。

判断文章是否机械#

连续几篇文章的小标题完全一样。
总结段把标题换进去就结束。
代码块与主题关系很弱。
没有具体命令、数据字段、参数或判断标准。

实战复盘#

复盘《个人博客文章模板优化》时，我会把它当成一个站点维护动作，而不是单篇文章。凡是影响首页、分类、RSS、Sitemap、搜索索引或旧链接的改动，都要在发布后做一次线上验证。

如果只在源码里看起来正确，但线上接口或页面没有变化，就说明构建或发布链路还有问题。博客维护类内容必须把“怎么确认已经生效”写清楚。

以后继续扩展这类文章时，可以补充真实命令输出、截图前后的差异，以及回滚路径。这样文章会更接近操作手册，而不是零散备忘。

最小验收样例#

验收《个人博客文章模板优化》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

文章模板要帮助写作进入状态，而不是替代思考。真正可复用的是写作流程，不能复用的是针对具体问题的判断。

博客卡片链接检查方法

Thu, 07 May 2026 00:00:00 GMT

博客卡片链接检查方法#

博客卡片是读者进入文章的入口。卡片样式再好看，如果链接错、标题被截断、文章数量不对，都会直接影响使用。

我检查卡片时，会同时看数据、布局和点击结果，而不是只看视觉效果。

链接先看真实 href#

卡片点击跳转通常由文章 slug 或分类 slug 生成。迁移文章后，如果路径规则变了，最容易出现卡片显示正常但点击 404。

浏览器里可以右键复制链接，也可以直接检查 DOM 中的 href。确认它和构建出的页面路径一致。

标题和数量要完整#

分类卡片里最重要的是分类名称和文章数量。如果图标或装饰元素挤占空间，应该优先保证文字可读。标题可以适度换行，但不要只露出一个字或省略到无法识别。

检查顺序#

数据层：分类数量是否来自真实文章统计。
路由层：点击后是否进入对应分类或文章。
视觉层：中文标题、长英文单词、数字是否溢出。
响应式：手机宽度下卡片是否仍然可点击、可阅读。

常用验证#

Terminal window

1
curl -I https://blog.tjcheng.cn/categories/
2
curl -I https://blog.tjcheng.cn/posts/backfill/2026-06-23/nginx-404-403-check/

视觉问题最好再用浏览器看一遍，因为构建通过不能证明布局没有被挤坏。

实战复盘#

复盘《博客卡片链接检查方法》时，我会把它当成一个站点维护动作，而不是单篇文章。凡是影响首页、分类、RSS、Sitemap、搜索索引或旧链接的改动，都要在发布后做一次线上验证。

如果只在源码里看起来正确，但线上接口或页面没有变化，就说明构建或发布链路还有问题。博客维护类内容必须把“怎么确认已经生效”写清楚。

以后继续扩展这类文章时，可以补充真实命令输出、截图前后的差异，以及回滚路径。这样文章会更接近操作手册，而不是零散备忘。

最小验收样例#

验收《博客卡片链接检查方法》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

卡片检查要以读者能不能找到文章为中心。图标、阴影和动画都应该让位于清楚的标题、数量和可访问链接。

博客页脚信息维护笔记

Wed, 06 May 2026 00:00:00 GMT

博客页脚信息维护笔记#

页脚通常不显眼，但它是站点可信度的一部分。版权年份、备案号、RSS、Sitemap、框架信息这些内容错了，读者不一定会马上反馈，但会显得网站没有维护。

我把页脚当成站点级信息来处理，不跟具体文章混在一起。

页脚应该放什么#

版权信息：站点名称和当前年份。
备案号：国内服务器和域名备案后需要展示。
RSS 与 Sitemap：给订阅和搜索引擎入口。
技术栈信息：如果主题保留 Powered by，可以确认链接是否仍然有效。

备案号链接#

备案号一般可以链接到工信部备案管理系统。展示时要保证文字完整，例如 陕ICP备2025077874号，不要因为布局挤压只显示一半。

移动端也要看一眼，页脚最容易因为行内链接太多而换行混乱。

维护时不要改散#

页脚应该集中在布局组件里维护，而不是每个页面复制一份。这样以后改备案号、RSS 链接或版权年份时，只需要改一个地方。

检查清单#

首页、文章页、分类页的页脚是否一致。
备案号是否可见、可点击。
RSS 和 Sitemap 是否返回 200。
页脚颜色在浅色和深色模式下是否可读。

实战复盘#

把《博客页脚信息维护笔记》真正用起来，我会在发布后回到站点里看三个位置：文章页、分类页和搜索结果。文章页看正文是否完整，分类页看它是否进入正确栏目，搜索结果看标题和摘要是否能被关键词命中。

如果这篇文章后续被修改，我会保留原始发布时间，只改正文和摘要。这样归档时间不会被频繁扰动，读者也能看出这篇内容是在哪个阶段整理出来的。

这类博客维护文章的验收标准不是“能不能发布”，而是以后遇到同类问题时，能不能按文章里的检查清单快速完成一次操作。

最小验收样例#

验收《博客页脚信息维护笔记》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

页脚不需要复杂，但要准确、稳定、全站一致。它是博客长期维护感最直接的细节之一。

博客构建日志怎么看

Tue, 05 May 2026 00:00:00 GMT

博客构建日志怎么看#

构建日志不是只有报错时才看。静态博客每次 build 都会告诉我们页面数量、警告、索引生成情况和最终产物位置。

读日志的关键是先看有没有失败，再看产物是否完整，最后判断警告是否影响线上页面。

先找退出结果#

真正失败通常会出现 error、failed、非零退出码，或者构建流程没有走到生成页面的阶段。只看到 warning 不一定需要回滚，但要知道它影响什么。

如果构建命令结束后没有生成新的 dist，就不能上线。

看页面数量#

Astro 构建会输出生成了多少页面。大规模新增文章后，页面数量应该明显增加。如果文章源文件增加了，但页面数量没变，要检查 draft、frontmatter 或内容集合配置。

Pagefind 日志里的 indexed pages 也很重要，它说明有多少页面进入搜索索引。

常用排查命令#

Terminal window

1
tail -n 80 /tmp/blog-build.log
2
grep -i "error\|failed\|warning" /tmp/blog-build.log
3
du -sh dist
4
find dist -name '*.html' | wc -l

警告怎么判断#

有些警告是可接受的，例如某些非文章页面没有正文可被 Pagefind 索引；有些警告则需要处理，例如 Markdown frontmatter 解析失败、图片路径不存在、组件属性错误。

判断标准很简单：它是否影响页面生成、内容展示、搜索索引或线上访问。

实战复盘#

复盘《博客构建日志怎么看》时，我会把它当成一个站点维护动作，而不是单篇文章。凡是影响首页、分类、RSS、Sitemap、搜索索引或旧链接的改动，都要在发布后做一次线上验证。

如果只在源码里看起来正确，但线上接口或页面没有变化，就说明构建或发布链路还有问题。博客维护类内容必须把“怎么确认已经生效”写清楚。

以后继续扩展这类文章时，可以补充真实命令输出、截图前后的差异，以及回滚路径。这样文章会更接近操作手册，而不是零散备忘。

最小验收样例#

验收《博客构建日志怎么看》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

构建日志要按顺序读：退出状态、页面数量、搜索索引、关键警告。只看最后一行，很容易漏掉内容层面的异常。

修改博客前的备份习惯

Mon, 04 May 2026 00:00:00 GMT

修改博客前的备份习惯#

博客看起来只是静态文件，但线上修改一旦覆盖错误，恢复起来仍然会花时间。尤其是批量迁移、替换 dist、修改 Nginx 配置时，备份是最便宜的保险。

我现在的习惯是：动源文件前备份源文件，动构建产物前备份 dist，动配置前备份配置。

备份哪些东西#

src/content/posts：文章源文件，最重要。
dist：当前线上可访问的构建产物，方便快速回滚。
Nginx 站点配置：一旦配置写错，网站可能直接打不开。
脚本和环境文件：例如构建脚本、部署脚本、包管理器配置。

备份命名要能看懂#

备份目录最好包含时间和原因，不要只叫 backup1。等问题发生时，能从目录名判断哪一个可以恢复。

Terminal window

1
mkdir -p /root/codex-backups/blog_web_app
2
cp -a src/content/posts /root/codex-backups/blog_web_app/posts-$(date +%Y%m%d%H%M%S)
3
cp -a dist /www/wwwroot/blog_app/blog_web_app/dist.prev.$(date +%Y%m%d%H%M%S)

什么时候必须备份#

单篇文章小修可以依赖 Git；但批量改几十篇文章、上传覆盖服务器目录、替换线上 dist、修改反向代理规则前，都应该做显式备份。

恢复也要提前想好#

备份不是只复制一份文件，还要知道怎么恢复。比如 dist 回滚时，要确认文件属主、路径和 Nginx 指向不变；文章回滚时，要重新构建搜索索引。

实战复盘#

我会用《修改博客前的备份习惯》建立一个可复用的维护标准：先说明为什么要做，再写具体检查项，最后给出发布后的确认方式。读者照着做时，不需要再猜下一步。

如果以后发现文章只有原则没有操作，就应该补一个最小命令或检查清单。维护博客本身也是工程工作，要能验证、能回滚、能复盘。

最小验收样例#

验收《修改博客前的备份习惯》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

备份的价值在于让修改可逆。只要改动影响线上可访问内容，就值得先留一条清晰的回退路径。

系列文章选题规划方法

Sun, 03 May 2026 00:00:00 GMT

系列文章选题规划方法#

单篇文章可以解决一个问题，但系列文章能建立一条学习路径。比如数据分析栏目里，读取、清洗、统计、导出如果各写一篇，就比零散记录更容易形成体系。

规划系列文章时，我会先确定读者从哪里开始、最终要能完成什么任务。

先确定系列边界#

一个系列不要试图包下所有知识。比如 pandas 系列可以只覆盖日常数据清洗，不必同时讲机器学习建模；OpenCV 系列可以先讲读图、颜色、阈值、轮廓，不急着进入深度学习。

边界越清楚，每篇文章越容易写深，而不是写成概念拼盘。

安排顺序#

我会按“输入 -> 处理 -> 验证 -> 输出”的顺序排文章。这样读者读完前一篇，就自然知道下一篇为什么存在。

例如：读取 CSV、字段类型检查、重复数据处理、日期列解析、合并、透视表、导出 Excel，这条线就很适合初学者跟着做。

每篇文章只承担一个目标#

标题只写一个核心动作。
开头说明这篇接在系列里的哪个位置。
代码示例只服务当前主题，不顺手塞太多扩展内容。
结尾指出下一步可以看哪类问题。

规划表模板#

1
系列名称：pandas 日常分析
2
目标读者：能写基础 Python，但经常卡在数据清洗
3
第 1 篇：读取 CSV 编码问题
4
第 2 篇：字段类型检查
5
第 3 篇：重复数据处理
6
完成标准：读者能从原始表格生成一份可检查的分析结果

实战复盘#

把《系列文章选题规划方法》真正用起来，我会在发布后回到站点里看三个位置：文章页、分类页和搜索结果。文章页看正文是否完整，分类页看它是否进入正确栏目，搜索结果看标题和摘要是否能被关键词命中。

这类博客维护文章的验收标准不是“能不能发布”，而是以后遇到同类问题时，能不能按文章里的检查清单快速完成一次操作。

最小验收样例#

验收《系列文章选题规划方法》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

系列文章不是把标题排成列表，而是设计一条可走完的路径。每篇只解决一个节点，整个栏目才会越来越清楚。

Frontmatter 日期字段使用规则

Sat, 02 May 2026 00:00:00 GMT

Frontmatter 日期字段使用规则#

日期字段看起来只是文章发布时间，但它会影响首页排序、归档页、RSS、搜索结果和读者对内容时效性的判断。

批量补文章时尤其要谨慎：如果所有文章都写同一天，归档页会显得非常机械，也不利于读者理解内容积累过程。

published 表示公开发布时间#

published 应该代表文章对外发布或整理完成的日期，而不是每次编辑的时间。后续修错别字、补一段代码，不需要频繁修改这个字段。

如果文章是迁移旧内容，原则上保留旧文章创建时间；如果是新补写的教程，可以选择今天之前合理分布的日期。

日期格式要稳定#

我建议统一使用 YYYY-MM-DD，不要混用 2026/05/02、中文日期或带时区的完整时间。静态站生成时，格式越统一，排序和解析越稳定。

1
published: 2026-05-02
2
draft: false
3
category: "博客相关分类"

批量新增时的检查#

日期是否都早于今天，避免未来文章意外提前展示。
同一批文章日期是否尽量不重复。
分类页排序是否符合预期。
RSS 中是否出现大量同一天的机械更新。

修改日期前先想清楚#

日期不是任意美化字段。改旧文章日期会改变归档历史，也可能影响搜索引擎对内容新旧的判断。除非文章被完全重写，否则我一般不改旧日期。

实战复盘#

我会用《Frontmatter 日期字段使用规则》建立一个可复用的维护标准：先说明为什么要做，再写具体检查项，最后给出发布后的确认方式。读者照着做时，不需要再猜下一步。

如果以后发现文章只有原则没有操作，就应该补一个最小命令或检查清单。维护博客本身也是工程工作，要能验证、能回滚、能复盘。

最小验收样例#

验收《Frontmatter 日期字段使用规则》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

frontmatter 的日期字段要当成内容元数据来维护。它不只是排序依据，也是博客长期可信度的一部分。

旧博客链接跳转整理

Fri, 01 May 2026 00:00:00 GMT

旧博客链接跳转整理#

博客迁移后，最容易被忽略的是旧链接。读者、搜索引擎、自己的收藏夹都可能还保存着旧地址，如果直接失效，就会把以前积累的入口变成 404。

旧链接跳转的目标不是把所有历史路径都永久保留，而是给重要文章和常用入口安排清晰的去向。

先列出需要保留的旧入口#

不是所有旧 URL 都值得写跳转规则。我会优先处理首页、分类页、访问量高的文章、外部平台曾经引用过的文章。

可以从旧站 sitemap、访问日志、搜索结果截图、浏览器收藏里整理路径清单。

跳转规则要一对一可解释#

如果旧文章在新博客里有对应文章，就做精确跳转；如果只是栏目迁移，就跳到新分类页；如果内容已经废弃，宁愿返回 404，也不要跳到无关页面。

1
location = /old-post.html {
2
    return 301 /posts/new-post-slug/;
3
}
4

5
location ^~ /old-category/ {
6
    return 301 /categories/;
7
}

验证跳转#

Terminal window

1
curl -I http://www.tjcheng.cn:1314/old-post.html
2
curl -L -o /dev/null -w '%{url_effective} %{http_code}\n' http://www.tjcheng.cn:1314/old-post.html

我会同时看状态码和最终 URL。301 表示永久跳转，适合路径已经稳定的新站；临时调整可以先用 302。

不要做的事#

把所有旧链接都跳到首页，会让读者找不到原内容。
新路径还没稳定就写 301，后面再改会增加维护成本。
只在前端写跳转，不处理服务器层面的旧入口。

实战复盘#

复盘《旧博客链接跳转整理》时，我会把它当成一个站点维护动作，而不是单篇文章。凡是影响首页、分类、RSS、Sitemap、搜索索引或旧链接的改动，都要在发布后做一次线上验证。

如果只在源码里看起来正确，但线上接口或页面没有变化，就说明构建或发布链路还有问题。博客维护类内容必须把“怎么确认已经生效”写清楚。

以后继续扩展这类文章时，可以补充真实命令输出、截图前后的差异，以及回滚路径。这样文章会更接近操作手册，而不是零散备忘。

最小验收样例#

验收《旧博客链接跳转整理》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

旧链接迁移的核心是尊重原来的访问意图。能精确对应就精确跳转，不能对应就给出合理栏目入口，不要用首页掩盖问题。

Sitemap 与 Robots 检查笔记

Thu, 30 Apr 2026 00:00:00 GMT

Sitemap 与 Robots 检查笔记#

Sitemap 和 robots 不是写给读者看的页面，但它们会影响搜索引擎理解站点结构。博客迁移、域名切换、路径调整后，这两个文件尤其值得检查。

我的目标不是追求复杂 SEO，而是保证搜索引擎能找到应该公开的文章，同时不要索引无意义页面。

Sitemap 负责告诉搜索引擎有哪些页面#

Sitemap 里应该包含公开文章、分类页、归档页等重要 URL。新增文章后，如果 sitemap 没更新，搜索引擎仍然可能通过链接发现文章，但效率会下降。

检查重点是域名是否正确、URL 是否是新站路径、时间是否更新。

Robots 负责说明哪些路径可以抓取#

robots.txt 不用于保护敏感内容，它只是给爬虫的抓取建议。真正不想公开的内容不能只靠 robots 隐藏。

博客里通常允许抓取公开页面，同时在 robots 里声明 sitemap 地址。

最小检查命令#

Terminal window

1
curl -I https://blog.tjcheng.cn/sitemap-index.xml
2
curl -I https://blog.tjcheng.cn/robots.txt
3
curl -s https://blog.tjcheng.cn/robots.txt

如果返回不是 200，先看构建产物是否存在，再看 Nginx 是否把静态文件正确暴露出来。

迁移后容易忽略的点#

sitemap 里还残留旧域名或旧端口。
robots 指向了不存在的 sitemap 文件。
文章路径从旧博客迁移后没有生成对应静态页面。
把草稿或测试页面也放进了公开索引。

实战复盘#

我会用《Sitemap 与 Robots 检查笔记》建立一个可复用的维护标准：先说明为什么要做，再写具体检查项，最后给出发布后的确认方式。读者照着做时，不需要再猜下一步。

如果以后发现文章只有原则没有操作，就应该补一个最小命令或检查清单。维护博客本身也是工程工作，要能验证、能回滚、能复盘。

最小验收样例#

验收《Sitemap 与 Robots 检查笔记》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

Sitemap 和 robots 的检查不复杂，但它们是站点发布质量的一部分。每次大规模新增或迁移文章后，都应该顺手确认一次。

Pagefind 搜索索引更新笔记

Wed, 29 Apr 2026 00:00:00 GMT

Pagefind 搜索索引更新笔记#

静态博客的搜索不是写完文章就自动可靠，Pagefind 需要在构建后扫描生成的 HTML。文章能打开，但搜索不到，通常就是索引没有重新生成或构建产物没有发布。

我检查 Pagefind 时，会同时看构建日志、索引文件和线上搜索效果。

Pagefind 做了什么#

Pagefind 会扫描构建后的页面，把正文内容拆成索引文件。它关注的是最终 HTML，不是 Markdown 源文件。所以只修改 src/content/posts 但没有重新 build，搜索结果不会变化。

如果构建日志里显示索引页面数量明显少于文章数量，就要检查是否有页面没有生成，或者某些页面被排除。

我会检查的文件#

Terminal window

1
ls -lh dist/pagefind/pagefind.js
2
find dist/pagefind -type f | wc -l
3
ls -lh dist/api/allPostMeta.json

pagefind.js 能访问说明前端搜索脚本存在；allPostMeta.json 更新说明文章元数据已经进入构建产物。这两个都正常，再去看搜索框的结果才有意义。

常见问题#

新文章页面是 200，但搜索不到：大概率没有重新构建 Pagefind。
本地能搜，线上搜不到：可能上传了 Markdown，却没有替换线上 dist。
搜索结果标题乱码：先检查 Markdown 文件编码是不是 UTF-8。
搜索结果太少：检查文章是否 draft，或构建日志里 Pagefind 扫描了多少页面。

发布后的验证#

发布后我会直接访问 /pagefind/pagefind.js，再打开 /api/allPostMeta.json 看文章总数。最后用新文章标题里的关键词搜索一次，例如 rolling、YOLO、Nginx。

实战复盘#

复盘《Pagefind 搜索索引更新笔记》时，我会把它当成一个站点维护动作，而不是单篇文章。凡是影响首页、分类、RSS、Sitemap、搜索索引或旧链接的改动，都要在发布后做一次线上验证。

如果只在源码里看起来正确，但线上接口或页面没有变化，就说明构建或发布链路还有问题。博客维护类内容必须把“怎么确认已经生效”写清楚。

以后继续扩展这类文章时，可以补充真实命令输出、截图前后的差异，以及回滚路径。这样文章会更接近操作手册，而不是零散备忘。

最小验收样例#

验收《Pagefind 搜索索引更新笔记》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

搜索问题不要只盯搜索框。先确认 Markdown 进入构建，再确认 HTML 被 Pagefind 扫描，最后才检查前端交互。

博客发布前复查流程

Tue, 28 Apr 2026 00:00:00 GMT

博客发布前复查流程#

博客发布前复查不是为了追求形式，而是为了防止低级错误进入线上页面。尤其是迁移文章、批量生成文章、修改 frontmatter 时，少一步检查就可能造成分类错乱或构建失败。

我给自己定的流程是：先看内容，再看元数据，然后构建，最后看线上页面。

内容层检查#

先通读标题、开头和小结，确认文章真的回答了标题提出的问题。正文不能只堆命令，也不能只写感受，至少要交代场景、步骤和验证结果。

技术文章尤其要检查代码块是否闭合、命令是否能复制运行、变量名是否前后一致。

元数据检查#

frontmatter 里的 title、published、description、tags、category 会直接影响列表页、分类页和搜索索引。批量处理时最容易出现日期重复、分类写错、摘要空泛的问题。

1
title: "Nginx 404 与 403 排查"
2
published: 2026-06-23
3
description: "从站点根目录、权限、location 匹配和错误日志四个方向区分 404 与 403。"
4
tags: ["问题解决", "Nginx"]
5
category: "问题解决"
6
draft: false

构建和线上检查#

本地或服务器构建通过只能说明没有语法错误，还要确认页面能访问、搜索索引更新、文章列表数量正确。

首页是否展示新文章。
分类页计数是否变化。
新文章 URL 是否返回 200。
搜索接口或 Pagefind 索引是否重新生成。

什么时候必须加严检查#

批量新增、迁移旧文章、修改路由结构、替换主题组件时，都要比日常写一篇文章更严格。因为这类改动影响的不是单个页面，而是整个站点结构。

实战复盘#

我会用《博客发布前复查流程》建立一个可复用的维护标准：先说明为什么要做，再写具体检查项，最后给出发布后的确认方式。读者照着做时，不需要再猜下一步。

如果以后发现文章只有原则没有操作，就应该补一个最小命令或检查清单。维护博客本身也是工程工作，要能验证、能回滚、能复盘。

最小验收样例#

验收《博客发布前复查流程》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

复查流程的价值在于固定顺序。只要每次都按内容、元数据、构建、线上四层走，很多问题会在发布前暴露。

博客图片路径整理笔记

Mon, 27 Apr 2026 00:00:00 GMT

博客图片路径整理笔记#

文章里的图片最怕迁移后变成空白，因为文字还能通过搜索找回来，图片路径一旦混乱，排查成本会很高。

我现在更倾向于把图片路径当成文章的一部分来管理：图片放在哪里、URL 怎么写、构建后是否还能访问，都要在发布前确认。

先区分三种图片来源#

第一种是 public 目录下的静态资源，适合头像、站点图标、通用截图。第二种是文章同目录资源，适合只服务于某一篇文章的图片。第三种是远程图片，适合临时引用，但长期可靠性最差。

如果一张图是文章理解的关键，不建议只引用外链。外链失效后，文章会失去上下文。

路径书写规则#

站点公共资源使用从根路径开始的地址，例如 /images/demo.png。
Markdown 中尽量避免 Windows 反斜杠路径，例如 C:\Users\...。
文件名使用英文、数字和短横线，减少空格、中文和特殊符号导致的编码问题。
同一篇文章多张图，可以放到同一个主题目录里。

迁移旧文章时怎么查#

迁移文章后，我会先搜索 ![]( 找出所有 Markdown 图片引用，再逐个检查本地文件是否存在。对于线上页面，还要打开开发者工具看图片请求是否返回 200。

Terminal window

1
rg -n "!\[.*\]\(" src/content/posts
2
find public -type f | sort | head

发布前检查#

页面首屏图片能否加载。
图片尺寸是否过大，是否需要压缩。
文件名大小写是否和引用完全一致，Linux 服务器区分大小写。
文章迁移后是否仍然引用了旧域名或旧端口。

实战复盘#

把《博客图片路径整理笔记》真正用起来，我会在发布后回到站点里看三个位置：文章页、分类页和搜索结果。文章页看正文是否完整，分类页看它是否进入正确栏目，搜索结果看标题和摘要是否能被关键词命中。

这类博客维护文章的验收标准不是“能不能发布”，而是以后遇到同类问题时，能不能按文章里的检查清单快速完成一次操作。

最小验收样例#

验收《博客图片路径整理笔记》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

图片路径最好在写文章时就规范下来。等文章数量变多后，再统一修复失效图片，会比修正文案麻烦得多。

博客分类和标签的使用规则

Sun, 26 Apr 2026 00:00:00 GMT

博客分类和标签的使用规则#

分类和标签看起来都是给文章做归档，但它们承担的职责不同。分类应该稳定，代表文章属于哪个长期栏目；标签可以更灵活，用来描述文章里出现的工具、框架或小主题。

如果分类和标签混用，后面文章变多以后，分类页会像杂物箱一样难找内容。

分类负责长期栏目#

分类数量不应该频繁膨胀。我的博客里更适合把分类维持在少数几个方向，例如数据结构与算法、数据分析、计算机视觉、问题解决、博客相关分类。

判断一篇文章放哪个分类，可以问一句：这篇文章三个月后还应该跟哪一组文章放在一起？如果答案不稳定，就不要新建分类。

标签负责细粒度检索#

标签可以写得更具体，例如 pandas、OpenCV、YOLO、Nginx、PowerShell。它们不一定形成完整栏目，但能帮助搜索和聚合。

同一篇文章可以有多个标签，但最好不要超过三到四个。标签太多时，通常说明文章主题没有收住。

发布时的判断顺序#

先确定文章的主要目标：教学、排错、记录流程，还是迁移复盘。
再选择一个稳定分类，避免为了单篇文章新建栏目。
最后补充工具型标签，方便以后按技术点检索。
如果两个分类都能放，优先放读者最可能寻找答案的位置。

常见误区#

把 pandas 这种工具名建成分类，导致数据分析栏目被拆碎。
每篇文章都新建一个标签，最后标签页没有聚合价值。
迁移旧文章时只保留标题，不重新判断它现在应该归属哪个栏目。

实战复盘#

复盘《博客分类和标签的使用规则》时，我会把它当成一个站点维护动作，而不是单篇文章。凡是影响首页、分类、RSS、Sitemap、搜索索引或旧链接的改动，都要在发布后做一次线上验证。

如果只在源码里看起来正确，但线上接口或页面没有变化，就说明构建或发布链路还有问题。博客维护类内容必须把“怎么确认已经生效”写清楚。

以后继续扩展这类文章时，可以补充真实命令输出、截图前后的差异，以及回滚路径。这样文章会更接近操作手册，而不是零散备忘。

最小验收样例#

验收《博客分类和标签的使用规则》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

分类要少而稳，标签要准而轻。先用分类建立博客的骨架，再用标签补充检索入口，文章越多越能体现价值。

博客标题与摘要检查清单

Sat, 25 Apr 2026 00:00:00 GMT

博客标题与摘要检查清单#

标题和摘要不是发布时顺手填的装饰字段，它们决定了文章在列表页、搜索结果和以后复盘时能不能被快速识别。

我给自己的原则是：标题负责说明具体问题，摘要负责交代场景、对象和解决结果。只要这两项含糊，文章内容再完整，也会在半年后变成很难找回的碎片。

标题先回答一个具体问题#

写标题时尽量避免只写“学习笔记”“问题记录”这种泛词。更好的写法是把技术点、动作和结果放进去，例如“pandas 读取 CSV 编码问题”比“pandas 笔记”更容易检索。

技术对象：pandas、Nginx、YOLO、OpenCV。
具体动作：读取、排查、迁移、构建、导出。
结果边界：编码问题、404/403、小样本训练、缓存未更新。

摘要要补足标题没有说完的信息#

摘要不需要重复标题，而是说明文章解决什么场景。比如标题已经写了“SSH 连接超时排查”，摘要就应该补充“从网络端口、安全组、sshd 服务和客户端参数四个层面定位”。

一个可用的摘要通常包含三块：遇到什么现象、检查哪些位置、读完能得到什么操作结论。

发布前检查清单#

标题里是否有明确对象，而不是只有“记录”“总结”。
摘要是否能独立说明文章价值，而不是把正文第一句复制一遍。
标题和分类是否一致，避免算法文章放到问题解决里。
搜索关键词是否自然出现，例如 Pagefind、frontmatter、rolling、YOLO。
列表页展示时是否会被截断后失去关键信息。

我会避免的写法#

最容易偷懒的写法是“某某问题整理笔记”，但读者无法从标题判断这是入门教程、排错记录，还是完整实践流程。以后回头找文章时，这种标题也最浪费时间。

实战复盘#

把《博客标题与摘要检查清单》真正用起来，我会在发布后回到站点里看三个位置：文章页、分类页和搜索结果。文章页看正文是否完整，分类页看它是否进入正确栏目，搜索结果看标题和摘要是否能被关键词命中。

这类博客维护文章的验收标准不是“能不能发布”，而是以后遇到同类问题时，能不能按文章里的检查清单快速完成一次操作。

最小验收样例#

验收《博客标题与摘要检查清单》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

小结#

标题和摘要的质量，本质上是在替未来的自己做索引。写清楚对象、动作和结果，文章才不会只在发布当天有用。

拓扑排序算法

Tue, 10 Mar 2026 12:40:21 GMT

拓扑排序算法#

拓扑排序用于有向无环图，也就是 DAG。

它要解决的问题是：如果一些任务之间有先后依赖，能不能排出一个合法顺序。

比如：

1
先学 A，才能学 B
2
先学 B，才能学 C

那么一种合法顺序是：

1
A B C

1、什么是拓扑序#

在有向图中，如果有一条边：

1
a -> b

表示 a 必须排在 b 前面。

如果一个序列满足所有边的先后关系，它就是拓扑序。

只有有向无环图才存在拓扑序。如果图里有环，就无法排出合法顺序。

2、核心思想：入度为 0 的点先处理#

入度表示有多少条边指向这个点。

如果一个点入度为 0，说明没有任何前置条件，可以先做。

拓扑排序的过程：

1
1. 把所有入度为 0 的点入队
2
2. 每次取出队头点 t
3
3. 删除 t 指向其他点的边
4
4. 如果某个点入度变成 0，就入队
5
5. 最后看是否处理了所有点

3、为什么能判断环#

如果图里有环，环上的每个点都至少有一个前置点也在环里。

这些点的入度不会变成 0，所以最后无法全部入队。

判断方式：

1
return tt == n - 1;

队列里存下来的节点数量等于 n，说明所有点都被处理了。

4、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 100010;
5
const int M = 200010;
6

7
int n, m;
8
int h[N], e[M], ne[M], idx;
9
int d[N];
10
int q[N];
11

12
void add(int a, int b) {
13
    e[idx] = b;
14
    ne[idx] = h[a];
15
    h[a] = idx++;
16
}
17

18
bool topsort() {
19
    int hh = 0;
20
    int tt = -1;
21

22
    for (int i = 1; i <= n; i++) {
23
        if (d[i] == 0) q[++tt] = i;
24
    }
25

26
    while (hh <= tt) {
27
        int t = q[hh++];
28

29
        for (int i = h[t]; i != -1; i = ne[i]) {
30
            int j = e[i];
31
            d[j]--;
32

33
            if (d[j] == 0) {
34
                q[++tt] = j;
35
            }
36
        }
37
    }
38

39
    return tt == n - 1;
40
}
41

42
int main() {
43
    cin >> n >> m;
44
    memset(h, -1, sizeof h);
45

46
    while (m--) {
47
        int a, b;
48
        cin >> a >> b;
49
        add(a, b);
50
        d[b]++;
51
    }
52

53
    if (topsort()) {
54
        for (int i = 0; i < n; i++) {
55
            cout << q[i] << " ";
56
        }
57
        cout << endl;
58
    } else {
59
        cout << "存在环，无拓扑序列" << endl;
60
    }
61

62
    return 0;
63
}

展开收起

5、手推一个例子#

有边：

1
1 -> 2
2
1 -> 3
3
2 -> 4
4
3 -> 4

一开始：

1
入度为 0 的点：1

处理 1 后，2 和 3 入度变成 0，入队。

处理 2 后，4 入度从 2 变成 1。

处理 3 后，4 入度从 1 变成 0，入队。

最后得到一种拓扑序：

1
1 2 3 4

也可能是：

1
1 3 2 4

拓扑序不一定唯一。

6、容易写错的地方#

（1）加边时要维护入度#

1
add(a, b);
2
d[b]++;

有向边 a -> b 会让 b 的入度加一。

（2）初始化邻接表#

1
memset(h, -1, sizeof h);

链式前向星必须初始化表头。

（3）判断条件是 `tt == n - 1`#

数组队列从下标 0 开始，最后一个元素位置是 n - 1。

如果处理节点数不够，说明有环。

总结#

拓扑排序的关键词是：

1
入度为 0 的点先入队

它既能输出一个满足依赖关系的顺序，也能判断有向图中是否存在环。

最小生成树Prim算法

Tue, 10 Mar 2026 11:51:55 GMT

最小生成树 Prim 算法#

Prim 算法用来求无向连通图的最小生成树。

最小生成树的意思是：选出一些边，把所有点连起来，并且总权重最小。

如果图不连通，就不存在最小生成树。

1、Prim 的核心思想#

Prim 像是在“不断扩展一个集合”。

刚开始生成树里只有一个点。每次从连接“树内点”和“树外点”的边里，选权重最小的一条，把新的点加入生成树。

重复这个过程，直到所有点都加入。

2、和 Dijkstra 的相似点#

Prim 和 Dijkstra 都会用到：

1
dist 数组
2
st 数组
3
小根堆

但含义不同：

Dijkstra 的 dist[j] 是起点到 j 的最短路。
Prim 的 dist[j] 是点 j 连接到当前生成树的最小边权。

3、什么时候更新 `dist`#

当一个点 p 加入生成树后，遍历它的所有邻边：

1
p -> j，边权 c

如果 j 还没有加入生成树，并且 c < dist[j]，就更新：

1
dist[j] = c;

4、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
typedef pair<int, int> PII;
5

6
const int N = 100010;
7
const int M = 200010;
8
const int INF = 0x3f3f3f3f;
9

10
int n, m;
11
int h[N], e[M], w[M], ne[M], idx;
12
int dista[N];
13
bool st[N];
14

15
void add(int a, int b, int c) {
16
    e[idx] = b;
17
    w[idx] = c;
18
    ne[idx] = h[a];
19
    h[a] = idx++;
20
}
21

22
int prim() {
23
    memset(dista, 0x3f, sizeof dista);
24

25
    priority_queue<PII, vector<PII>, greater<PII>> heap;
26
    heap.push({0, 1});
27
    dista[1] = 0;
28

29
    int cnt = 0;
30
    int ans = 0;
31

32
    while (!heap.empty()) {
33
        auto t = heap.top();
34
        heap.pop();
35

36
        int distance = t.first;
37
        int ver = t.second;
38

39
        if (st[ver]) continue;
40

41
        st[ver] = true;
42
        cnt++;
43
        ans += distance;
44

45
        for (int i = h[ver]; i != -1; i = ne[i]) {
46
            int j = e[i];
47
            int c = w[i];
48

49
            if (!st[j] && c < dista[j]) {
50
                dista[j] = c;
51
                heap.push({dista[j], j});
52
            }
53
        }
54
    }
55

56
    if (cnt < n) return -1;
57
    return ans;
58
}
59

60
int main() {
61
    scanf("%d%d", &n, &m);
62
    memset(h, -1, sizeof h);
63

64
    while (m--) {
65
        int a, b, c;
66
        scanf("%d%d%d", &a, &b, &c);
67
        add(a, b, c);
68
        add(b, a, c);
69
    }
70

71
    printf("%d\n", prim());
72
    return 0;
73
}

展开收起

5、为什么无向边要加两次#

如果题目给的是无向图：

1
a -- b

存图时要写：

1
add(a, b, c);
2
add(b, a, c);

这样从 a 能走到 b，从 b 也能走到 a。

6、怎么判断图不连通#

Prim 每次成功加入一个新点，就让 cnt++。

如果最后：

1
cnt < n

说明不是所有点都能被连上，图不连通，没有最小生成树。

7、容易写错的地方#

（1）边数组要开两倍#

无向图每条边存两次，所以：

1
const int M = 200010;

如果 m 最大是 100000，边数组至少要开 2 * m。

（2）Prim 的 `dist` 不是起点最短路#

它表示“连接到当前生成树的最小边权”。

（3）加入生成树时再累加答案#

1
ans += distance;

这个点真正被选中时，才把连接它的边权加入答案。

总结#

Prim 的关键词是：

1
从树外选一条最小边，把新点加入生成树

它和 Dijkstra 写法很像，但 dist 的意义不同。理解这一点，模板就不容易混。

Dijkstra算法

Tue, 10 Mar 2026 11:49:52 GMT

Dijkstra 算法#

Dijkstra 算法用来求“非负权图”中的单源最短路。

单源最短路的意思是：从一个起点出发，到其他点的最短距离。

这里整理的是堆优化版本，适合边数比较多、点数也比较大的情况。

1、适用条件#

Dijkstra 有一个前提：

1
边权不能是负数

如果图中有负权边，就不能直接用 Dijkstra。

常见场景：

1
给 n 个点、m 条有向边，求 1 号点到 n 号点的最短距离。

2、核心思想#

维护一个距离数组：

1
dist[i]

表示从起点到 i 的当前最短距离。

每次从还没有确定最短路的点中，取出距离最小的点 ver。因为所有边权非负，所以这个点的最短距离已经确定。

然后用它去更新邻点：

1
如果 dist[j] > dist[ver] + w
2
就更新 dist[j]

这个过程叫“松弛”。

3、为什么用小根堆#

普通 Dijkstra 每次要扫描所有点找最小距离，复杂度高。

堆优化版本用优先队列维护：

1
{距离, 点编号}

每次直接取出当前距离最小的点。

4、链式前向星存图#

1
int h[N], e[M], w[M], ne[M], idx;

含义：

1
h[a]：点 a 的第一条边
2
e[i]：第 i 条边的终点
3
w[i]：第 i 条边的权重
4
ne[i]：同起点的下一条边

加边：

1
void add(int a, int b, int c) {
2
    e[idx] = b;
3
    w[idx] = c;
4
    ne[idx] = h[a];
5
    h[a] = idx++;
6
}

5、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
typedef pair<int, int> PII;
5

6
const int N = 150010;
7
const int M = 150010;
8
const int INF = 0x3f3f3f3f;
9

10
int n, m;
11
int h[N], e[M], w[M], ne[M], idx;
12
int dista[N];
13
bool st[N];
14

15
void add(int a, int b, int c) {
16
    e[idx] = b;
17
    w[idx] = c;
18
    ne[idx] = h[a];
19
    h[a] = idx++;
20
}
21

22
int dijkstra() {
23
    memset(dista, 0x3f, sizeof dista);
24

25
    priority_queue<PII, vector<PII>, greater<PII>> heap;
26

27
    dista[1] = 0;
28
    heap.push({0, 1});
29

30
    while (!heap.empty()) {
31
        auto t = heap.top();
32
        heap.pop();
33

34
        int distance = t.first;
35
        int ver = t.second;
36

37
        if (st[ver]) continue;
38
        st[ver] = true;
39

40
        for (int i = h[ver]; i != -1; i = ne[i]) {
41
            int j = e[i];
42

43
            if (dista[j] > distance + w[i]) {
44
                dista[j] = distance + w[i];
45
                heap.push({dista[j], j});
46
            }
47
        }
48
    }
49

50
    if (dista[n] == INF) return -1;
51
    return dista[n];
52
}
53

54
int main() {
55
    scanf("%d%d", &n, &m);
56
    memset(h, -1, sizeof h);
57

58
    while (m--) {
59
        int a, b, c;
60
        scanf("%d%d%d", &a, &b, &c);
61
        add(a, b, c);
62
    }
63

64
    printf("%d\n", dijkstra());
65
    return 0;
66
}

展开收起

6、`st` 数组的作用#

1
bool st[N];

st[ver] = true 表示 ver 的最短距离已经确定。

堆里可能会存在同一个点的多个距离版本。比如先入堆一个较大的距离，后来又找到更短距离。旧版本不会马上消失，所以取出来时要判断：

1
if (st[ver]) continue;

7、容易写错的地方#

（1）不要在 `#define` 后面加分号#

如果写：

1
#define x first;

会导致展开后多出分号。更推荐直接用：

1
t.first
2
t.second

（2）初始化邻接表#

1
memset(h, -1, sizeof h);

没有初始化，遍历边时会出错。

（3）Dijkstra 不能处理负权边#

只要出现负权边，就要考虑 Bellman-Ford、SPFA 或其他算法。

总结#

Dijkstra 可以记成：

1
小根堆取最近点 -> 标记最短路已确定 -> 用它松弛所有出边

它适合非负权图，是图论最短路里非常常用的模板。

线段树与懒标记

Thu, 04 Dec 2025 03:52:19 GMT

线段树与懒标记#

线段树适合处理区间问题，比如：

区间求和
区间最大值
单点修改
区间修改

当题目既有区间查询，又有区间修改时，通常需要懒标记。

1、线段树解决什么问题#

假设有数组：

1
1 2 3 4 5

需要频繁执行：

1
查询 [l, r] 的和
2
把 [l, r] 中每个数都加上 c

如果每次都暴力遍历区间，复杂度太高。线段树可以把这些操作做到 O(log n)。

2、线段树节点存什么#

常见节点结构：

1
struct Node {
2
    int l, r;
3
    long long sum;
4
    long long add;
5
} tr[N * 4];

含义：

1
l, r：当前节点表示的区间
2
sum：当前区间的和
3
add：懒标记，表示这个区间整体还欠着多少增量没有下传

3、建树#

建树就是递归划分区间。

1
void build(int u, int l, int r) {
2
    tr[u] = {l, r, a[l], 0};
3

4
    if (l == r) return;
5

6
    int mid = (l + r) >> 1;
7
    build(u << 1, l, mid);
8
    build(u << 1 | 1, mid + 1, r);
9
    pushup(u);
10
}

u 是当前节点编号，左儿子是 u << 1，右儿子是 u << 1 | 1。

4、pushup：用子节点更新父节点#

1
void pushup(int u) {
2
    tr[u].sum = tr[u << 1].sum + tr[u << 1 | 1].sum;
3
}

父节点的区间和等于左右子区间的和。

5、懒标记是什么#

如果某次修改完全覆盖当前区间，就不需要继续递归到叶子节点。

比如要让 [1, 100] 都加 5，当前节点刚好表示 [1, 100]，直接更新：

1
sum += 区间长度 * 5
2
add += 5

这个 add 表示：以后如果需要访问子节点，再把这个修改传下去。

6、pushdown：下传懒标记#

1
void pushdown(int u) {
2
    auto& root = tr[u];
3
    auto& left = tr[u << 1];
4
    auto& right = tr[u << 1 | 1];
5

6
    if (root.add) {
7
        left.add += root.add;
8
        left.sum += (long long)(left.r - left.l + 1) * root.add;
9

10
        right.add += root.add;
11
        right.sum += (long long)(right.r - right.l + 1) * root.add;
12

13
        root.add = 0;
14
    }
15
}

展开收起

只有当要继续往下访问子节点时，才需要 pushdown。

7、完整模板：区间加，区间求和#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 100010;
5

6
int n, m;
7
long long a[N];
8

9
struct Node {
10
    int l, r;
11
    long long sum;
12
    long long add;
13
} tr[N * 4];
14

15
void pushup(int u) {
16
    tr[u].sum = tr[u << 1].sum + tr[u << 1 | 1].sum;
17
}
18

19
void build(int u, int l, int r) {
20
    tr[u] = {l, r, a[l], 0};
21

22
    if (l == r) return;
23

24
    int mid = (l + r) >> 1;
25
    build(u << 1, l, mid);
26
    build(u << 1 | 1, mid + 1, r);
27
    pushup(u);
28
}
29

30
void pushdown(int u) {
31
    auto& root = tr[u];
32
    auto& left = tr[u << 1];
33
    auto& right = tr[u << 1 | 1];
34

35
    if (root.add) {
36
        left.add += root.add;
37
        left.sum += (long long)(left.r - left.l + 1) * root.add;
38

39
        right.add += root.add;
40
        right.sum += (long long)(right.r - right.l + 1) * root.add;
41

42
        root.add = 0;
43
    }
44
}
45

46
void modify(int u, int l, int r, int d) {
47
    if (tr[u].l >= l && tr[u].r <= r) {
48
        tr[u].sum += (long long)(tr[u].r - tr[u].l + 1) * d;
49
        tr[u].add += d;
50
        return;
51
    }
52

53
    pushdown(u);
54

55
    int mid = (tr[u].l + tr[u].r) >> 1;
56
    if (l <= mid) modify(u << 1, l, r, d);
57
    if (r > mid) modify(u << 1 | 1, l, r, d);
58

59
    pushup(u);
60
}
61

62
long long query(int u, int l, int r) {
63
    if (tr[u].l >= l && tr[u].r <= r) {
64
        return tr[u].sum;
65
    }
66

67
    pushdown(u);
68

69
    int mid = (tr[u].l + tr[u].r) >> 1;
70
    long long res = 0;
71

72
    if (l <= mid) res += query(u << 1, l, r);
73
    if (r > mid) res += query(u << 1 | 1, l, r);
74

75
    return res;
76
}
77

78
int main() {
79
    cin >> n >> m;
80
    for (int i = 1; i <= n; i++) cin >> a[i];
81

82
    build(1, 1, n);
83

84
    while (m--) {
85
        char op;
86
        int l, r, d;
87
        cin >> op >> l >> r;
88

89
        if (op == 'Q') {
90
            cout << query(1, l, r) << endl;
91
        } else {
92
            cin >> d;
93
            modify(1, l, r, d);
94
        }
95
    }
96

97
    return 0;
98
}

展开收起

8、容易写错的地方#

（1）数组要开 `4 * N`#

线段树节点数量一般开：

1
tr[N * 4]

不要只开 N。

（2）区间和建议用 `long long`#

区间加和区间求和很容易超过 int。

（3）查询和修改前要下传懒标记#

只要要访问子节点，就先：

1
pushdown(u);

否则子节点保存的值可能不是最新的。

原图笔记#

懒标记处理#

总结图#

总结#

线段树可以记成：

1
build 建树
2
pushup 子节点更新父节点
3
pushdown 懒标记下传
4
modify 区间修改
5
query 区间查询

懒标记的意义是：能不往下走就先不往下走，把修改暂存在当前节点，等真正需要访问子节点时再下传。

并查集

Thu, 04 Dec 2025 02:40:12 GMT

并查集#

并查集用来维护“若干个元素属于哪些集合”。

它最常见的两个操作是：

查询两个元素是否在同一个集合。
合并两个元素所在的集合。

1、可以解决什么问题#

比如有 1 ~ 5 五个点，刚开始每个点都是单独集合：

1
{1} {2} {3} {4} {5}

执行：

1
合并 1 和 2
2
合并 2 和 3

之后集合变成：

1
{1, 2, 3} {4} {5}

这时查询 1 和 3 是否连通，答案就是是。

2、核心思想：用父节点表示集合#

并查集用数组 p 表示每个点的父节点。

如果：

1
p[x] == x

说明 x 是这个集合的根节点，也叫祖宗节点。

两个点是否在同一个集合，就看它们的祖宗节点是否一样。

3、查找祖宗节点#

基础写法：

1
int find(int x) {
2
    if (p[x] != x) return find(p[x]);
3
    return x;
4
}

但这样树可能很深，所以通常加路径压缩：

1
int find(int x) {
2
    if (p[x] != x) p[x] = find(p[x]);
3
    return p[x];
4
}

路径压缩会把查询路径上的点直接挂到根节点下面，后续查询更快。

4、合并两个集合#

合并 a 和 b 所在集合：

1
p[find(a)] = find(b);

意思是：让 a 的祖宗节点指向 b 的祖宗节点。

5、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 100010;
5

6
int n, m;
7
int p[N];
8

9
int find(int x) {
10
    if (p[x] != x) p[x] = find(p[x]);
11
    return p[x];
12
}
13

14
int main() {
15
    cin >> n >> m;
16

17
    for (int i = 1; i <= n; i++) p[i] = i;
18

19
    while (m--) {
20
        char op;
21
        int a, b;
22
        cin >> op >> a >> b;
23

24
        if (op == 'M') {
25
            p[find(a)] = find(b);
26
        } else {
27
            if (find(a) == find(b)) cout << "Yes" << endl;
28
            else cout << "No" << endl;
29
        }
30
    }
31

32
    return 0;
33
}

展开收起

6、带集合大小的并查集#

有些题会问某个集合里有多少个点，可以多维护一个 sz 数组。

1
int p[N], sz[N];
2

3
for (int i = 1; i <= n; i++) {
4
    p[i] = i;
5
    sz[i] = 1;
6
}
7

8
void merge(int a, int b) {
9
    int pa = find(a);
10
    int pb = find(b);
11

12
    if (pa != pb) {
13
        p[pa] = pb;
14
        sz[pb] += sz[pa];
15
    }
16
}

展开收起

查询集合大小时：

1
sz[find(x)]

7、容易写错的地方#

（1）初始化不能漏#

1
for (int i = 1; i <= n; i++) p[i] = i;

刚开始每个点都是自己的祖宗。

（2）合并的是祖宗，不是普通节点#

错误写法：

1
p[a] = b;

正确写法：

1
p[find(a)] = find(b);

（3）查询也要用 `find`#

1
find(a) == find(b)

不能直接比较 p[a] 和 p[b]。

原图笔记#

总结#

并查集可以记住两个函数：

1
find：找祖宗
2
merge：合并集合

路径压缩是并查集高效的关键。只要所有查询和合并都通过 find，模板就比较稳定。

图的存储

Sat, 29 Nov 2025 03:09:53 GMT

图的存储#

图论题的第一步通常不是跑算法，而是先把图存起来。

不同存储方式适合不同场景。常见方式有：

邻接矩阵
边集数组
邻接表
链式前向星

1、先理解图里的基本元素#

图由点和边组成。

如果有一条边：

1
a -> b，权重为 c

那么存图时至少要记录：

1
起点 a
2
终点 b
3
权重 c

如果是无向图，一条边 a - b 通常要存两次：

1
a -> b
2
b -> a

2、邻接矩阵#

邻接矩阵用二维数组存边：

1
int g[N][N];

如果 g[a][b] = c，表示从 a 到 b 有一条权重为 c 的边。

初始化时一般写：

1
memset(g, 0x3f, sizeof g);
2
for (int i = 1; i <= n; i++) g[i][i] = 0;

加边：

1
g[a][b] = min(g[a][b], c);

邻接矩阵的优点是查询两点之间是否有边很快，O(1)。

缺点是空间复杂度是 O(n^2)，点数大时开不下。

3、边集数组#

边集数组就是把每条边直接存成一个结构体：

1
struct Edge {
2
    int a, b, w;
3
};
4

5
vector<Edge> edges;

加边：

1
edges.push_back({a, b, w});

这种写法适合 Kruskal 最小生成树，因为 Kruskal 需要把所有边拿出来排序。

4、vector 邻接表#

如果要经常遍历某个点的所有出边，可以用邻接表：

1
vector<pair<int, int>> g[N];

其中：

1
g[a] 存从 a 出发的所有边
2
pair 的 first 是终点，second 是权重

加边：

1
g[a].push_back({b, c});

遍历：

1
for (auto item : g[a]) {
2
    int b = item.first;
3
    int c = item.second;
4
}

这种写法直观，适合学习和一般题目。

5、链式前向星#

竞赛模板里经常使用链式前向星，本质上是用数组模拟邻接表。

1
const int N = 100010;
2
const int M = 200010;
3

4
int h[N], e[M], w[M], ne[M], idx;

含义：

1
h[a]：点 a 的第一条边编号
2
e[i]：第 i 条边的终点
3
w[i]：第 i 条边的权重
4
ne[i]：与第 i 条边同起点的下一条边编号
5
idx：当前边编号

初始化：

1
memset(h, -1, sizeof h);

加边：

1
void add(int a, int b, int c) {
2
    e[idx] = b;
3
    w[idx] = c;
4
    ne[idx] = h[a];
5
    h[a] = idx++;
6
}

遍历点 a 的所有出边：

1
for (int i = h[a]; i != -1; i = ne[i]) {
2
    int b = e[i];
3
    int c = w[i];
4
}

6、完整链式前向星模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 100010;
5
const int M = 200010;
6

7
int n, m;
8
int h[N], e[M], w[M], ne[M], idx;
9

10
void add(int a, int b, int c) {
11
    e[idx] = b;
12
    w[idx] = c;
13
    ne[idx] = h[a];
14
    h[a] = idx++;
15
}
16

17
int main() {
18
    cin >> n >> m;
19
    memset(h, -1, sizeof h);
20

21
    while (m--) {
22
        int a, b, c;
23
        cin >> a >> b >> c;
24
        add(a, b, c);
25
    }
26

27
    for (int a = 1; a <= n; a++) {
28
        cout << a << ":";
29
        for (int i = h[a]; i != -1; i = ne[i]) {
30
            cout << " -> " << e[i] << "(" << w[i] << ")";
31
        }
32
        cout << endl;
33
    }
34

35
    return 0;
36
}

展开收起

7、怎么选择存图方式#

1
点数小、要快速查边：邻接矩阵
2
要给所有边排序：边集数组
3
要遍历每个点的出边：邻接表
4
追求数组模板和性能：链式前向星

8、原图笔记#

下面保留原来的图示，方便对照复习。

邻接矩阵#

边集数组#

邻接表#

链式邻接表#

链式前向星#

总结#

图的存储方式会影响后面算法的写法。学习 Dijkstra、Prim、拓扑排序这类算法时，建议优先掌握链式前向星，因为它和竞赛模板结合得最紧。

YOLO11环境配置

Tue, 14 Oct 2025 06:21:44 GMT

YOLO 11环境配置#

1、硬件环境#

（1）确定硬件环境（内存尽可能大于等于16GB）#

（2）尽量存在显卡GPU环境（显存大于等于6GB）#

（3）本文使用的window系统（其他系统需要找其他教程）#

2、下载YOLO源代码#

GitHub - ultralytics/ultralytics at v8.3.163

本文使用的是v8.3.163的版本，因为计算机技术版本迭代版本过快，防止后续出现版本冲突的问题，所以我们尽可能保持版本一致。

3、下载预训练模型#

Releases · ultralytics/assets

因为我们下载的源代码是v8.3.163版本，那么对应的预训练模型的板块就是8.3.0版本

在网页上快捷键按住ctrl+f打开搜索框，输入yolo11n，可以找到yolo系列中最小的几个模型

yolo11n-grayscale.pt对应的是灰度图目标检测模型，yolo11n.pt对应的是目标检测模型，其他模型也是对应其他任务的模型，可以自行查阅。

我们为了后续便于学习，可以先下载yolo11n、cls、obb、pose、seg这五个模型，与yolo源代码放置在一起。

4、下载 Anaconda下载#

Index of /anaconda/archive/ | 清华大学开源软件镜像站 | Tsinghua Open Source Mirror

下载2024.06-1的版本，防止出现版本更新的版本冲突问题

在安装时，尽量选择安装用户为Just Me，若选择All Users用户后，在后续需要转存文件位置为DEF盘，会出现，环境配置文件在c盘下，主体文件在DEF盘的位置，出现位置不一致，不便于环境配置。

后续的安装默认即可。

打开Anaconda prompt命令行，输入notepad .condarc

再生成的配置文件中，加入第三方镜像源的配置内容，然后保存退出

1
channels:
2
  - defaults
3
show_channel_urls: true
4
default_channels:
5
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
6
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
7
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2
8
custom_channels:
9
  conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
10
  pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud

在命令行中，继续输入type .condarc验证是否保存成功

如果出现找不到文件，可能是给.condarc文件默认添加了文件后缀.txt，可以尝试type .condarc.txt命令，若出现了上面的正确配置内容，我们需要去对应目录，将文件后缀名.txt删除，然后继续往后进行。

然后继续在命令行输入 pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple，给pip配置镜像源，出现如下，说明配置成功

5、环境配置#

前言：我们安装Anaconda可以很方便的对python环境进行管理，一个项目所需要的python版本以及第三方库的版本是需要相互适应的，高版本的python对应的低版本的第三方库可能就会发生冲突，无法正确运行，这就导致，我们需要将每一个项目分离开来，方便对环境的统一隔离管理。

conda命令与pip命令的使用

6、安装Yolo环境#

这里我们创建名称为yolo3_11的环境，python版本指定为3.11，具体命令可以参考上面的常用命令

输入conda activate yolo3_11切换当前的环境，可以查看前面的（）中的内容，当前的环境。

7、安装pytorch#

本质pytorch其实也是一个第三方库，但是他对系统硬件显卡等有要求，不然无法正确运行，所以在安装前，我们先需要确定我们的硬件设备性能。

显卡的型号，显卡驱动的版本

如果我们是非50系显卡，那么，我们可以在命令行输入nvidia-smi，注意需要在base环境下：

如果该数值大于等于12.8就说明符合要求，我们就可以直接开始安装pytorch，否则需要重新安装显卡驱动。在网页上搜索英伟达显卡驱动，找到手动搜索显卡型号，找到对应驱动，下载一个版本后，一直默认安装即可，安装后重启即可。

pytorch下载网址：Get Started

选择以前的版本，注意不要下载错了，若后续出现了冲突问题，可能难以找到问题根源

将该命令复制到命令行，注意环境的位置，若在base环境下执行，则会将pytorch安装到base环境下，所以我们需要切换到我们需要安装到的环境中。

出现报错了，不要担心，原命令使用官网的方式下载，会很慢，会出现报错。可以使用镜像源下载

1
pip install torch==2.5.0 torchvision==0.20.0 torchaudio==2.5.0 -f https://mirrors.aliyun.com/pytorch-wheels/cu118

在安装完成后，我们输入pip show torch验证安装

进一步对pytorch进行验证

然后，ctrl+z退出即可，到这里没有任何报错，说明pytorch已经成功安装了！

8、安装其他第三方库#

关闭命令行，重新再次打开，找到我们的yolo源代码路径，在命令行中使用pushd命令，其主要与linux中的cd命令一致

然后输入下面的命令，会直接根据其给出的第三方库的列表，会直接自动安装所需的第三方库。

1
pip install -e .

9、运行测试#

模型与源代码放置统一目录下

输入命令 yolo detect predict

预测结果会生成到 runs\detect\predict目录下。

高精度除低精度

Sat, 11 Oct 2025 12:51:56 GMT

高精度除低精度#

高精度除低精度指的是：

1
一个很大的整数 A 除以一个普通整数 b

例如：

1
123456789123456789 / 7

大整数用字符串读入，小整数 b 用 int 存。

1、核心思想#

除法和加减乘不同，它更适合从高位往低位处理。

手算除法时也是从最高位开始：

1
当前余数 r 先乘 10，再加上当前位
2
当前商位 = r / b
3
新的余数 = r % b

2、为什么输入仍然倒序存储#

为了和高精度加减乘保持一致，我们仍然把数字倒序存入 vector：

1
12345 -> [5, 4, 3, 2, 1]

但做除法时从高位开始，所以循环从 A.size() - 1 往 0 走。

3、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
vector<int> divide(vector<int>& A, int b, int& r) {
5
    vector<int> C;
6
    r = 0;
7

8
    for (int i = A.size() - 1; i >= 0; i--) {
9
        r = r * 10 + A[i];
10
        C.push_back(r / b);
11
        r %= b;
12
    }
13

14
    reverse(C.begin(), C.end());
15

16
    while (C.size() > 1 && C.back() == 0) C.pop_back();
17

18
    return C;
19
}
20

21
int main() {
22
    string a;
23
    int b;
24
    cin >> a >> b;
25

26
    vector<int> A;
27
    for (int i = a.size() - 1; i >= 0; i--) {
28
        A.push_back(a[i] - '0');
29
    }
30

31
    int r = 0;
32
    vector<int> C = divide(A, b, r);
33

34
    for (int i = C.size() - 1; i >= 0; i--) printf("%d", C[i]);
35
    printf("\n%d\n", r);
36

37
    return 0;
38
}

展开收起

这里输出两行：

1
第一行：商
2
第二行：余数

如果题目只要求商，就可以不输出余数。

4、为什么要 `reverse`#

循环从高位到低位处理，所以 C.push_back 的顺序是从商的高位到低位。

为了和其他高精度模板保持一致，最后把 C 翻转成“低位在前”：

1
reverse(C.begin(), C.end());

这样输出仍然可以统一使用：

1
for (int i = C.size() - 1; i >= 0; i--)

5、手推一个例子#

计算：

1
123 / 5

从高位开始：

1
r = 1，商位 0，余数 1
2
r = 1 * 10 + 2 = 12，商位 2，余数 2
3
r = 2 * 10 + 3 = 23，商位 4，余数 3

商是 024，去掉前导零后是 24，余数是 3。

6、容易写错的地方#

（1）`string` 不要写成 `sting`#

1
string a;

（2）除法不能从低位开始#

竖式除法必须从最高位开始处理。

（3）要去掉商的前导零#

1
while (C.size() > 1 && C.back() == 0) C.pop_back();

（4）不要忘记函数调用分号#

1
vector<int> C = divide(A, b, r);

总结#

高精度除低精度可以记成：

1
从高位到低位：r = r * 10 + 当前位，商位 = r / b，余数 = r % b

它本质上就是把手算竖式除法翻译成代码。

高精度乘低精度

Thu, 09 Oct 2025 13:55:45 GMT

高精度乘低精度#

高精度乘低精度指的是：

1
一个很大的整数 A 乘以一个普通整数 b

比如：

1
123456789123456789 * 7

大整数 A 用字符串读入，小整数 b 可以用 int 存。

1、核心思想#

仍然是模拟竖式。

从个位开始，每一位都乘以 b，再加上上一位传来的进位。

例如：

1
123 * 4

倒序看：

1
3 * 4 = 12，当前位 2，进位 1
2
2 * 4 + 1 = 9，当前位 9，进位 0
3
1 * 4 = 4，当前位 4

结果是：

1
492

2、为什么循环条件里要有 `t`#

模板里常见这一句：

1
for (int i = 0; i < A.size() || t; i++)

意思是：即使所有位都处理完了，只要还有进位，就继续处理。

比如：

1
999 * 9

最后会多出高位进位。

3、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
vector<int> mul(vector<int>& A, int b) {
5
    vector<int> C;
6

7
    int t = 0;
8
    for (int i = 0; i < (int)A.size() || t; i++) {
9
        if (i < (int)A.size()) t += A[i] * b;
10

11
        C.push_back(t % 10);
12
        t /= 10;
13
    }
14

15
    while (C.size() > 1 && C.back() == 0) C.pop_back();
16

17
    return C;
18
}
19

20
int main() {
21
    string a;
22
    int b;
23
    cin >> a >> b;
24

25
    vector<int> A;
26
    for (int i = a.size() - 1; i >= 0; i--) {
27
        A.push_back(a[i] - '0');
28
    }
29

30
    vector<int> C = mul(A, b);
31

32
    for (int i = C.size() - 1; i >= 0; i--) printf("%d", C[i]);
33

34
    return 0;
35
}

展开收起

4、处理乘以 0#

如果 b = 0，循环仍然能得到结果 0。

因为 C 最后会保留一个数字，不会被前导零清理删空：

1
while (C.size() > 1 && C.back() == 0) C.pop_back();

5、容易写错的地方#

（1）`string` 不要写成 `sting`#

1
string a;

拼写错误会直接编译失败。

（2）字符要减 `'0'`#

1
A.push_back(a[i] - '0');

不能直接存 a[i]。

（3）函数调用后要加分号#

1
vector<int> C = mul(A, b);

（4）输出的是 `C[i]`#

1
printf("%d", C[i]);

不是输出整个 vector。

6、复杂度#

如果大整数有 n 位，那么每一位处理一次：

1
时间复杂度 O(n)
2
空间复杂度 O(n)

总结#

高精度乘低精度记住一句话：

1
当前位 = A[i] * b + 进位

然后取个位放入答案，把十位以上继续作为进位。

高精度减法

Wed, 08 Oct 2025 04:56:55 GMT

高精度减法#

高精度减法也是模拟竖式。和加法相比，它多了两个问题：

要判断两个大整数谁更大。
做减法时要处理借位。

通常我们先保证 A >= B，然后计算 A - B。如果原本 A < B，就计算 B - A，输出时前面加负号。

1、为什么要先比较大小#

例如：

1
123 - 456

结果是负数。

为了让减法函数只处理一种情况，我们可以先判断：

1
如果 A >= B，输出 A - B
2
如果 A < B，输出 -(B - A)

这样 sub 函数内部只需要处理“大数减小数”。

2、倒序存储#

和高精度加法一样，先把字符串倒序存入数组：

1
12345 -> [5, 4, 3, 2, 1]

这样从个位开始减，借位也好处理。

3、借位怎么写#

设 t 表示上一位是否借位。

当前位先减掉借位：

1
t = A[i] - t;

再减去 B[i]：

1
if (i < B.size()) t -= B[i];

当前位结果：

1
(t + 10) % 10

如果 t < 0，说明需要向高位借 1。

4、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
bool cmp(vector<int>& A, vector<int>& B) {
5
    if (A.size() != B.size()) return A.size() > B.size();
6

7
    for (int i = A.size() - 1; i >= 0; i--) {
8
        if (A[i] != B[i]) return A[i] > B[i];
9
    }
10

11
    return true;
12
}
13

14
vector<int> sub(vector<int>& A, vector<int>& B) {
15
    vector<int> C;
16

17
    int t = 0;
18
    for (int i = 0; i < (int)A.size(); i++) {
19
        t = A[i] - t;
20
        if (i < (int)B.size()) t -= B[i];
21

22
        C.push_back((t + 10) % 10);
23

24
        if (t < 0) t = 1;
25
        else t = 0;
26
    }
27

28
    while (C.size() > 1 && C.back() == 0) C.pop_back();
29

30
    return C;
31
}
32

33
int main() {
34
    string a, b;
35
    cin >> a >> b;
36

37
    vector<int> A, B;
38

39
    for (int i = a.size() - 1; i >= 0; i--) A.push_back(a[i] - '0');
40
    for (int i = b.size() - 1; i >= 0; i--) B.push_back(b[i] - '0');
41

42
    vector<int> C;
43

44
    if (cmp(A, B)) {
45
        C = sub(A, B);
46
    } else {
47
        C = sub(B, A);
48
        printf("-");
49
    }
50

51
    for (int i = C.size() - 1; i >= 0; i--) printf("%d", C[i]);
52

53
    return 0;
54
}

展开收起

5、为什么要去掉前导零#

比如：

1
1000 - 999 = 1

数组里可能得到：

1
[1, 0, 0, 0]

倒序输出会变成 0001，所以要去掉高位多余的 0：

1
while (C.size() > 1 && C.back() == 0) C.pop_back();

保留 C.size() > 1 是为了避免结果为 0 时把最后一个 0 也删掉。

6、容易写错的地方#

（1）比较大小要从最高位开始#

因为数组是倒序存储，高位在 back() 附近，所以比较时从后往前。

（2）借位变量要在每一位更新#

1
if (t < 0) t = 1;
2
else t = 0;

t 不再是当前位结果，而是下一位需要减掉的借位。

（3）负号只输出一次#

不要在 sub 函数里处理负号，让主函数根据大小判断输出即可。

总结#

高精度减法可以拆成：

1
先比较大小 -> 大数减小数 -> 逐位借位 -> 去掉前导零

这和手算竖式完全一致，只是数组为了方便从低位开始存。

高精度加法

Wed, 08 Oct 2025 04:55:23 GMT

高精度加法#

高精度加法用于处理超过 long long 范围的大整数相加。

C++ 的整数类型有上限，但题目可能给出几百位甚至几千位的数字。这时就不能直接用 int 或 long long，需要用字符串读入，再手动模拟竖式加法。

1、核心思想#

比如计算：

1
123 + 89

手算时会从个位开始：

1
3 + 9 = 12，写 2 进 1
2
2 + 8 + 1 = 11，写 1 进 1
3
1 + 1 = 2

结果是：

1
212

程序里也一样，从低位到高位逐位相加。

2、为什么倒序存储#

字符串 "123" 的下标从左到右是高位到低位。

但加法要从个位开始，所以我们把它倒序存入数组：

1
字符串：1 2 3
2
数组：  3 2 1

这样数组下标 0 就是个位，处理进位很方便。

3、模板步骤#

1
1. 字符串读入两个大整数
2
2. 倒序存入 vector
3
3. 从低位到高位逐位相加
4
4. 用 t 保存进位
5
5. 最后倒序输出结果

4、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
vector<int> add(vector<int>& A, vector<int>& B) {
5
    vector<int> C;
6

7
    int t = 0;
8
    for (int i = 0; i < (int)A.size() || i < (int)B.size(); i++) {
9
        if (i < (int)A.size()) t += A[i];
10
        if (i < (int)B.size()) t += B[i];
11

12
        C.push_back(t % 10);
13
        t /= 10;
14
    }
15

16
    if (t) C.push_back(t);
17

18
    return C;
19
}
20

21
int main() {
22
    string a, b;
23
    cin >> a >> b;
24

25
    vector<int> A, B;
26

27
    for (int i = a.size() - 1; i >= 0; i--) A.push_back(a[i] - '0');
28
    for (int i = b.size() - 1; i >= 0; i--) B.push_back(b[i] - '0');
29

30
    vector<int> C = add(A, B);
31

32
    for (int i = C.size() - 1; i >= 0; i--) printf("%d", C[i]);
33

34
    return 0;
35
}

展开收起

5、手推代码里的 `t`#

t 同时承担两个作用：

1
当前位相加的和 + 上一位进位

每次：

1
C.push_back(t % 10);
2
t /= 10;

t % 10 是当前位结果，t / 10 是进位。

6、容易写错的地方#

（1）最后的进位不能漏#

1
if (t) C.push_back(t);

比如：

1
999 + 1 = 1000

最后会多出一个进位。

（2）字符要减 `'0'`#

1
A.push_back(a[i] - '0');

否则存进去的是字符编码，不是数字。

（3）输出时要倒序#

数组低位在前，所以输出时要从后往前：

1
for (int i = C.size() - 1; i >= 0; i--)

总结#

高精度加法就是模拟竖式：

1
倒序存储 -> 逐位相加 -> 处理进位 -> 倒序输出

只要把“低位在数组前面”这个约定记住，后面的高精度减法、乘法、除法也会更容易理解。

区间合并

Sun, 05 Oct 2025 01:15:06 GMT

区间合并#

区间合并用来处理多个区间之间的重叠关系。

比如：

1
[1, 3] 和 [2, 4]

这两个区间有交集，可以合并成：

1
[1, 4]

1、问题描述#

给出若干个区间，要求把所有有交集的区间合并，最后得到互不重叠的区间。

例如：

1
[1, 3] [2, 6] [8, 10] [9, 12]

合并后：

1
[1, 6] [8, 12]

2、核心思路#

区间合并一般分两步：

1
1. 按左端点从小到大排序
2
2. 从前往后维护当前正在合并的区间 [st, ed]

排序后，只需要看当前区间和维护区间是否相交。

3、如何判断是否相交#

假设当前维护区间是：

1
[st, ed]

新来的区间是：

1
[l, r]

如果：

1
ed < l

说明两个区间完全分开，需要开启一个新区间。

否则说明有交集，可以合并：

1
ed = max(ed, r)

4、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
typedef pair<int, int> PII;
5

6
int n;
7
vector<PII> segs;
8

9
void merge_segments(vector<PII>& segs) {
10
    vector<PII> res;
11

12
    sort(segs.begin(), segs.end());
13

14
    int st = -2e9;
15
    int ed = -2e9;
16

17
    for (auto seg : segs) {
18
        int l = seg.first;
19
        int r = seg.second;
20

21
        if (ed < l) {
22
            if (st != -2e9) res.push_back({st, ed});
23
            st = l;
24
            ed = r;
25
        } else {
26
            ed = max(ed, r);
27
        }
28
    }
29

30
    if (st != -2e9) res.push_back({st, ed});
31

32
    segs = res;
33
}
34

35
int main() {
36
    cin >> n;
37

38
    for (int i = 0; i < n; i++) {
39
        int l, r;
40
        cin >> l >> r;
41
        segs.push_back({l, r});
42
    }
43

44
    merge_segments(segs);
45

46
    cout << segs.size() << endl;
47
    return 0;
48
}

展开收起

5、手推一遍#

输入：

1
[1, 3] [2, 6] [8, 10] [9, 12]

先排序，顺序不变。

处理 [1, 3]：

1
当前区间 = [1, 3]

处理 [2, 6]，因为 2 <= 3，有交集：

1
当前区间 = [1, 6]

处理 [8, 10]，因为 6 < 8，开启新区间：

1
保存 [1, 6]
2
当前区间 = [8, 10]

处理 [9, 12]，有交集：

1
当前区间 = [8, 12]

最后保存 [8, 12]。

6、容易写错的地方#

（1）忘记先排序#

不排序的话，无法保证只和当前维护区间比较就够了。

（2）最后一个区间忘记加入答案#

循环结束后还要：

1
if (st != -2e9) res.push_back({st, ed});

（3）相邻端点是否合并要看题意#

当前模板中：

1
if (ed < l)

表示 [1, 3] 和 [3, 5] 会合并。

如果题目认为端点相接不算重叠，就要改成：

1
if (ed <= l)

总结#

区间合并的关键词是：

1
按左端点排序 + 维护当前右端点

只要能判断新区间是否和当前区间相交，代码就很直接。

数据离散化

Sat, 04 Oct 2025 08:23:57 GMT

数据离散化#

离散化用来处理“值域很大，但实际出现的数很少”的问题。

比如坐标范围是 0 到 10^9，但题目只给了 10^5 个点。如果直接开数组，肯定开不下。这时就可以把这些大坐标映射到连续的小下标。

1、离散化是什么#

假设原始坐标是：

1
1 234 542 8245 1000000000

离散化后可以变成：

1
1 2 3 4 5

它不关心原值之间到底差多少，只关心它们的相对顺序。

2、离散化的三个步骤#

1
1. 收集所有会用到的坐标
2
2. 排序并去重
3
3. 用二分找到每个坐标对应的新下标

这里“所有会用到的坐标”很重要。查询边界也要收集进去。

3、排序去重模板#

1
vector<int> alls;
2

3
sort(alls.begin(), alls.end());
4
alls.erase(unique(alls.begin(), alls.end()), alls.end());

unique 只会把重复元素挪到后面，并返回去重后末尾位置，所以还要配合 erase 真正删除。

4、二分映射模板#

1
int find(int x) {
2
    int l = 0;
3
    int r = alls.size() - 1;
4

5
    while (l < r) {
6
        int mid = (l + r) >> 1;
7
        if (alls[mid] >= x) r = mid;
8
        else l = mid + 1;
9
    }
10

11
    return r + 1;
12
}

这里返回 r + 1，是因为后面要配合前缀和使用，数组从 1 开始更方便。

5、典型问题#

题目给出：

n 次加法操作：在位置 x 上加 c。
m 次查询：查询区间 [l, r] 的和。

坐标可能很大，但操作和查询次数有限，所以可以离散化。

6、完整 C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
typedef pair<int, int> PII;
5

6
const int N = 300010;
7

8
int n, m;
9
int a[N], s[N];
10

11
vector<int> alls;
12
vector<PII> add_ops;
13
vector<PII> query_ops;
14

15
int find_index(int x) {
16
    int l = 0;
17
    int r = alls.size() - 1;
18

19
    while (l < r) {
20
        int mid = (l + r) >> 1;
21
        if (alls[mid] >= x) r = mid;
22
        else l = mid + 1;
23
    }
24

25
    return r + 1;
26
}
27

28
int main() {
29
    cin >> n >> m;
30

31
    for (int i = 0; i < n; i++) {
32
        int x, c;
33
        cin >> x >> c;
34
        add_ops.push_back({x, c});
35
        alls.push_back(x);
36
    }
37

38
    for (int i = 0; i < m; i++) {
39
        int l, r;
40
        cin >> l >> r;
41
        query_ops.push_back({l, r});
42
        alls.push_back(l);
43
        alls.push_back(r);
44
    }
45

46
    sort(alls.begin(), alls.end());
47
    alls.erase(unique(alls.begin(), alls.end()), alls.end());
48

49
    for (auto item : add_ops) {
50
        int x = find_index(item.first);
51
        a[x] += item.second;
52
    }
53

54
    for (int i = 1; i <= (int)alls.size(); i++) {
55
        s[i] = s[i - 1] + a[i];
56
    }
57

58
    for (auto item : query_ops) {
59
        int l = find_index(item.first);
60
        int r = find_index(item.second);
61
        cout << s[r] - s[l - 1] << endl;
62
    }
63

64
    return 0;
65
}

展开收起

7、为什么查询边界也要加入 `alls`#

如果只收集加法操作的位置，查询 [l, r] 的 l 和 r 可能根本不在离散数组中。

比如只有位置 100 有值，但查询是 [1, 1000000000]。如果不收集 1 和 1000000000，就无法把查询边界映射到正确下标。

8、容易写错的地方#

（1）忘记去重#

重复坐标如果不去掉，会影响二分映射和前缀和下标。

（2）返回下标是否加 1 要统一#

如果前缀和从 1 开始，就返回 r + 1。

如果数组从 0 开始，就返回 r。

两种写法都可以，但整篇代码必须统一。

（3）`alls.size()` 是无符号类型#

写循环时可以转成 int：

1
for (int i = 1; i <= (int)alls.size(); i++)

避免类型比较警告。

总结#

离散化的目的不是改变大小关系，而是把稀疏的大坐标压缩成连续小下标。

1
收集坐标 -> 排序去重 -> 二分映射 -> 在小下标数组上处理

在新的python虚拟环境中使用jupter

Fri, 03 Oct 2025 10:41:36 GMT

在新的python虚拟环境中使用jupyter#

步骤一：在对应的虚拟环境中安装库#

1
# 三个都可以试试，因为存在版本的问题
2
 版本较老：conda install nb_conda
3
 安装失败的可以试试这个：conda install jupyter notebook
4
 Python 是3.11版本可以使用:conda install -c conda-forge nb_conda

步骤二：修改jupyter打开的默认文件路径#

在激活的环境中，执行以下命令生成配置文件

1
jupyter notebook --generate-config

执行后会在用户目录的 .jupyter 文件夹中生成 jupyter_notebook_config.py 文件（路径类似：C:\Users\你的用户名.jupyter\jupyter_notebook_config.py，我们需要确定虚拟环境中的该配置文件位置）。

步骤三：修改配置文件中的默认路径#

找到并打开 jupyter_notebook_config.py 文件，搜索（或手动定位）以下配置项：

1
# c.NotebookApp.notebook_dir = ''

去掉行首的注释符号 #，并将其值改为你想要的默认文件路径（例如 D:\MyJupyterProjects，注意路径用正斜杠 / 或双反斜杠 \）：

1
c.NotebookApp.notebook_dir = 'D:/MyJupyterProjects'  # 替换为你的目标路径

步骤四：在对应的虚拟环境中运行命令即可#

保存配置文件后，在激活的 conda 环境中启动 Jupyter Notebook：

1
jupyter notebook

确定显卡的支持Pytorch版本

Fri, 03 Oct 2025 10:03:25 GMT

安装pytorch的条件#

步骤 1：检查显卡驱动支持的 CUDA 版本#

打开命令提示符（CMD）或终端，输入以下命令：

1
nvidia-smi

在输出结果的右上角，会显示 “CUDA Version: xx.x”（例如 CUDA Version: 12.9），这是你的驱动支持的最高 CUDA 版本。

步骤 2：选择匹配的 PyTorch CUDA 版本#

PyTorch 提供了多个 CUDA 版本（如 12.6、12.8、12.9），请选择不超过你显卡驱动支持版本的最高 CUDA 版本（例如驱动支持 12.9，就选 CUDA 12.9）。如果你的电脑没有 NVIDIA 显卡（或不想用 GPU 加速），则选择CPU 版本。

步骤 3：执行对应安装命令#

假设你的驱动支持CUDA 12.9，且使用 Python 3.11，在 PyTorch 环境中执行以下pip命令：

1
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu129

如果选择CPU 版本，命令为：

1
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

步骤 4：安装pytorch库#

pytorch网址：https://pytorch.ac.cn/get-started/locally/ 根据步骤二选择对应的内容，然后在anaconda虚拟环境中，运行命令即可。注意：安装文件可能需要3分钟或以上，耐心等待即可。

验证安装#

安装完成后，可通过以下代码验证 PyTorch 和 CUDA 是否正常工作：

1
import torch
2
print("PyTorch版本:", torch.__version__)
3
print("是否支持CUDA:", torch.cuda.is_available())
4
if torch.cuda.is_available():
5
    print("CUDA版本:", torch.version.cuda)
6
    print("显卡型号:", torch.cuda.get_device_name(0))

若输出中torch.cuda.is_available()为True，且 CUDA 版本与你选择的一致，则安装成功。

conda下载路径的修改

Fri, 03 Oct 2025 09:27:50 GMT

问题：在Anaconda Navigator中创建新的虚拟环境，默认的路径Location是 C:\User***.conda\envs。#

方法一：管理员运行#

1、修改conda配置文件

（1）添加新路径

使用命令行（Anaconda Prompt）将新的路径设置为虚拟环境的存储位置：

1
conda config --add envs_dirs D:\ProgramData\anaconda3\envs

这里的 D:\anaconda_envs 是你希望存储虚拟环境的路径，可以更换为任何你喜欢的目录。

（2）查看配置是否生效

运行以下命令查看配置：

1
conda config --show envs_dirs

3、直接创建新的虚拟环境

【重要：需要对Anaconda Prompt使用“以管理员身份运行”】

（未使用管理员身份运行Anaconda Prompt，直接创建虚拟环境，会默认存储在默认路径C:\user***.conda\envs）

1
conda create -n my_new

4、运行以下命令验证虚拟环境的位置：

1
conda info --envs

方法二：修改文件权限#

打开文件资源管理器，导航到 D:\soft\Anaconda3\，找到 envs 文件夹（如果没有则手动创建）。
右键 envs 文件夹 → 属性 → 安全选项卡。点击编辑 → 添加，在弹出的窗口中输入你的用户名（比如 TengJ），点击检查名称确认，然后点击确定。
在 “组或用户名” 中选中你的账户，在下方 “权限” 列表中勾选 “完全控制”（至少勾选 “读取” 和 “写入”），点击应用 → 确定。

差分

Fri, 03 Oct 2025 07:45:42 GMT

差分#

差分可以看作前缀和的反向操作。前缀和擅长快速查询区间和，差分擅长快速做区间修改。

如果题目经常出现：

1
把区间 [l, r] 中每个数都加上 c

那么差分就是很适合的工具。

1、一维差分的思想#

假设原数组是 a，差分数组是 b：

1
b[1] = a[1]
2
b[2] = a[2] - a[1]
3
b[3] = a[3] - a[2]
4
...

那么对 b 求前缀和，就能还原 a：

1
a[i] = b[1] + b[2] + ... + b[i]

2、为什么区间加能变成 O(1)#

如果想让 [l, r] 都加上 c，只需要：

1
b[l] += c
2
b[r + 1] -= c

原因是：

从 l 开始，前缀和都会多加 c。
到 r + 1 时，再减掉 c，让后面的数恢复原样。

3、一维差分模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 100010;
5

6
int n, m;
7
int a[N], b[N];
8

9
void insert(int l, int r, int c) {
10
    b[l] += c;
11
    b[r + 1] -= c;
12
}
13

14
int main() {
15
    scanf("%d%d", &n, &m);
16

17
    for (int i = 1; i <= n; i++) scanf("%d", &a[i]);
18

19
    for (int i = 1; i <= n; i++) {
20
        insert(i, i, a[i]);
21
    }
22

23
    while (m--) {
24
        int l, r, c;
25
        scanf("%d%d%d", &l, &r, &c);
26
        insert(l, r, c);
27
    }
28

29
    for (int i = 1; i <= n; i++) {
30
        b[i] += b[i - 1];
31
        printf("%d ", b[i]);
32
    }
33

34
    return 0;
35
}

展开收起

4、二维差分解决什么问题#

二维差分对应的是矩阵里的子矩形修改：

1
把左上角 (x1, y1) 到右下角 (x2, y2) 的所有元素都加上 c

如果直接遍历子矩形，复杂度可能很高。二维差分可以把一次矩形修改变成 O(1)。

5、二维差分公式#

对子矩形加 c：

1
b[x1][y1] += c
2
b[x2 + 1][y1] -= c
3
b[x1][y2 + 1] -= c
4
b[x2 + 1][y2 + 1] += c

最后对差分矩阵做二维前缀和，就能得到修改后的原矩阵。

6、二维差分模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 1010;
5

6
int n, m, q;
7
int a[N][N], b[N][N];
8

9
void insert(int x1, int y1, int x2, int y2, int c) {
10
    b[x1][y1] += c;
11
    b[x2 + 1][y1] -= c;
12
    b[x1][y2 + 1] -= c;
13
    b[x2 + 1][y2 + 1] += c;
14
}
15

16
int main() {
17
    scanf("%d%d%d", &n, &m, &q);
18

19
    for (int i = 1; i <= n; i++) {
20
        for (int j = 1; j <= m; j++) {
21
            scanf("%d", &a[i][j]);
22
            insert(i, j, i, j, a[i][j]);
23
        }
24
    }
25

26
    while (q--) {
27
        int x1, y1, x2, y2, c;
28
        scanf("%d%d%d%d%d", &x1, &y1, &x2, &y2, &c);
29
        insert(x1, y1, x2, y2, c);
30
    }
31

32
    for (int i = 1; i <= n; i++) {
33
        for (int j = 1; j <= m; j++) {
34
            b[i][j] += b[i - 1][j] + b[i][j - 1] - b[i - 1][j - 1];
35
            printf("%d ", b[i][j]);
36
        }
37
        printf("\n");
38
    }
39

40
    return 0;
41
}

展开收起

7、差分和前缀和的关系#

可以这样理解：

1
差分数组 --做前缀和--> 原数组
2
原数组 --相邻项相减--> 差分数组

所以差分最后一定要“还原”，也就是做一次前缀和。

8、容易写错的地方#

（1）一维区间右端要写 `r + 1`#

1
b[r + 1] -= c;

这是让影响在 r 后面停止。

（2）二维右下角是 `x2 + 1, y2 + 1`#

1
b[x2 + 1][y2 + 1] += c;

不要写成 b[x2][y2] += c。

（3）还原二维矩阵时列数用 `m`#

1
for (int j = 1; j <= m; j++)

不要把列循环写成 j <= n。

总结#

差分适合“多次区间修改，最后一次性输出结果”的问题。

1
一维：b[l] += c, b[r + 1] -= c
2
二维：四个角做加减

前缀和

Thu, 02 Oct 2025 02:27:52 GMT

前缀和#

前缀和用来快速求区间和。它的核心是提前做一次预处理，把“每次都遍历区间”变成“两个数组值相减”。

1、为什么需要前缀和#

假设有数组：

1
1 2 3 4 5

如果想求 [2, 4] 的和，也就是：

1
2 + 3 + 4 = 9

普通做法是每次循环一遍区间，复杂度是 O(n)。

如果有很多次查询，这样会很慢。前缀和可以把每次查询降到 O(1)。

2、一维前缀和公式#

定义：

1
s[i] = a[1] + a[2] + ... + a[i]

那么：

1
s[i] = s[i - 1] + a[i]

查询 [l, r] 的区间和：

1
a[l] + ... + a[r] = s[r] - s[l - 1]

3、一维前缀和模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 100010;
5

6
int n, m;
7
int a[N], s[N];
8

9
int main() {
10
    scanf("%d%d", &n, &m);
11

12
    for (int i = 1; i <= n; i++) scanf("%d", &a[i]);
13

14
    for (int i = 1; i <= n; i++) {
15
        s[i] = s[i - 1] + a[i];
16
    }
17

18
    while (m--) {
19
        int l, r;
20
        scanf("%d%d", &l, &r);
21
        printf("%d\n", s[r] - s[l - 1]);
22
    }
23

24
    return 0;
25
}

展开收起

这里建议数组从 1 开始存，这样 s[l - 1] 更自然。

4、二维前缀和解决什么问题#

二维前缀和用于快速求一个子矩阵的和。

比如矩阵里要查询左上角 (x1, y1) 到右下角 (x2, y2) 这个矩形区域的总和。

5、二维前缀和公式#

构造公式：

1
s[i][j] = s[i - 1][j] + s[i][j - 1] - s[i - 1][j - 1] + a[i][j]

查询公式：

1
sum = s[x2][y2]
2
    - s[x1 - 1][y2]
3
    - s[x2][y1 - 1]
4
    + s[x1 - 1][y1 - 1]

可以理解为：先取大矩形，再减掉上面和左边多算的部分，最后把左上角被减了两次的区域加回来。

6、二维前缀和模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 1010;
5

6
int n, m, q;
7
int a[N][N], s[N][N];
8

9
int main() {
10
    scanf("%d%d%d", &n, &m, &q);
11

12
    for (int i = 1; i <= n; i++) {
13
        for (int j = 1; j <= m; j++) {
14
            scanf("%d", &a[i][j]);
15
        }
16
    }
17

18
    for (int i = 1; i <= n; i++) {
19
        for (int j = 1; j <= m; j++) {
20
            s[i][j] = s[i - 1][j] + s[i][j - 1] - s[i - 1][j - 1] + a[i][j];
21
        }
22
    }
23

24
    while (q--) {
25
        int x1, y1, x2, y2;
26
        scanf("%d%d%d%d", &x1, &y1, &x2, &y2);
27
        printf("%d\n", s[x2][y2] - s[x1 - 1][y2] - s[x2][y1 - 1] + s[x1 - 1][y1 - 1]);
28
    }
29

30
    return 0;
31
}

展开收起

7、容易写错的地方#

（1）二维构造时循环边界写错#

1
for (int j = 1; j <= m; j++)

不要写成 j < m，否则最后一列不会被处理。

（2）查询循环变量写错#

二维前缀和通常有 q 次查询：

1
while (q--)

不要误写成 while (m--)。

（3）查询公式下标写混#

记住是：

1
右下 - 上方 - 左方 + 左上

总结#

前缀和适合“多次区间求和”。一维记住：

1
s[r] - s[l - 1]

二维记住：

1
大矩形 - 上面 - 左边 + 左上角

整数二分

Wed, 01 Oct 2025 07:55:20 GMT

整数二分#

整数二分最容易让人混乱的地方不是循环，而是边界。很多题不是直接问“某个数在哪里”，而是问：

第一个满足条件的位置在哪里。
最后一个满足条件的位置在哪里。

这两种问题对应两套模板。

1、什么时候可以二分#

只要答案区间具有单调性，就可以考虑二分。

比如一个数组满足：

1
小于 x 的部分 | 大于等于 x 的部分

那么“第一个大于等于 x 的位置”就可以二分。

再比如：

1
满足条件的部分 | 不满足条件的部分

或者反过来，只要能被某个 check(mid) 分成两段，就能二分。

2、模板一：找左边界#

当区间被分成：

1
[l, mid] 和 [mid + 1, r]

通常是在找第一个满足条件的位置。

1
int bsearch_left(int l, int r) {
2
    while (l < r) {
3
        int mid = (l + r) >> 1;
4
        if (check(mid)) r = mid;
5
        else l = mid + 1;
6
    }
7
    return l;
8
}

这里 check(mid) 表示：答案可能在 mid 或 mid 左边。

3、模板二：找右边界#

当区间被分成：

1
[l, mid - 1] 和 [mid, r]

通常是在找最后一个满足条件的位置。

1
int bsearch_right(int l, int r) {
2
    while (l < r) {
3
        int mid = (l + r + 1) >> 1;
4
        if (check(mid)) l = mid;
5
        else r = mid - 1;
6
    }
7
    return l;
8
}

这里 mid 要写成：

1
int mid = (l + r + 1) >> 1;

原因是当 l + 1 == r 时，如果还用 (l + r) >> 1，mid 会等于 l，可能导致死循环。

4、例子：有序数组中查找 x 的范围#

给定有序数组：

1
1 2 2 2 3 4

查找 2 第一次和最后一次出现的位置。

左边界是第一个 >= 2 的位置。

右边界是最后一个 <= 2 的位置。

5、完整代码#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 100010;
5

6
int n, q;
7
int a[N];
8
int x;
9

10
bool check_left(int mid) {
11
    return a[mid] >= x;
12
}
13

14
bool check_right(int mid) {
15
    return a[mid] <= x;
16
}
17

18
int bsearch_left(int l, int r) {
19
    while (l < r) {
20
        int mid = (l + r) >> 1;
21
        if (check_left(mid)) r = mid;
22
        else l = mid + 1;
23
    }
24
    return l;
25
}
26

27
int bsearch_right(int l, int r) {
28
    while (l < r) {
29
        int mid = (l + r + 1) >> 1;
30
        if (check_right(mid)) l = mid;
31
        else r = mid - 1;
32
    }
33
    return l;
34
}
35

36
int main() {
37
    cin >> n >> q;
38
    for (int i = 0; i < n; i++) cin >> a[i];
39

40
    while (q--) {
41
        cin >> x;
42

43
        int l = bsearch_left(0, n - 1);
44
        if (a[l] != x) {
45
            cout << "-1 -1" << endl;
46
        } else {
47
            int r = bsearch_right(0, n - 1);
48
            cout << l << " " << r << endl;
49
        }
50
    }
51

52
    return 0;
53
}

展开收起

6、如何判断用哪个模板#

可以先问一句：

1
答案更像是左边界，还是右边界？

如果是找“第一个满足条件”，用左边界模板。

如果是找“最后一个满足条件”，用右边界模板。

7、容易写错的地方#

（1）右边界模板忘记 `+1`#

1
int mid = (l + r + 1) >> 1;

这是防止死循环的关键。

（2）`check` 的含义不清楚#

写二分前先用一句话定义 check(mid)。

比如：

1
check(mid)：a[mid] 是否大于等于 x

定义清楚后，更新边界就不容易乱。

（3）没有检查答案是否存在#

二分只能找到边界，不能保证目标值一定存在。所以找到位置后还要判断：

1
if (a[l] != x)

总结#

整数二分不要硬背一堆变形。先记住两套模板：

1
找左边界：mid = (l + r) >> 1
2
找右边界：mid = (l + r + 1) >> 1

然后把 check(mid) 的含义写清楚，边界更新就会自然很多。

归并排序

Sun, 28 Sep 2025 13:04:35 GMT

归并排序#

归并排序也是分治算法。它和快速排序的区别是：快速排序先划分再递归，归并排序先递归再合并。

归并排序的核心思想是：

1
先把左右两半分别排好，再把两个有序数组合成一个有序数组。

1、问题描述#

给定数组：

1
5 3 8 4 2

要求从小到大排序：

1
2 3 4 5 8

如果把数组不断二分，最后每个小区间只有一个数。一个数天然有序，然后再一层层合并回来。

2、归并排序的基本步骤#

1
1. 找到中点 mid
2
2. 递归排序左半边 [l, mid]
3
3. 递归排序右半边 [mid + 1, r]
4
4. 用双指针把两个有序区间合并到临时数组
5
5. 把临时数组复制回原数组

核心是第 4 步：合并两个有序区间。

3、合并两个有序区间#

假设左边是：

1
2 5 8

右边是：

1
3 4 9

合并时用两个指针：

1
i 指向左区间当前元素
2
j 指向右区间当前元素
3
谁小就先放进临时数组

得到：

1
2 3 4 5 8 9

4、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 1000010;
5

6
int n;
7
int q[N], tmp[N];
8

9
void merge_sort(int q[], int l, int r) {
10
    if (l >= r) return;
11

12
    int mid = (l + r) >> 1;
13
    merge_sort(q, l, mid);
14
    merge_sort(q, mid + 1, r);
15

16
    int i = l;
17
    int j = mid + 1;
18
    int k = 0;
19

20
    while (i <= mid && j <= r) {
21
        if (q[i] <= q[j]) tmp[k++] = q[i++];
22
        else tmp[k++] = q[j++];
23
    }
24

25
    while (i <= mid) tmp[k++] = q[i++];
26
    while (j <= r) tmp[k++] = q[j++];
27

28
    for (i = l, j = 0; i <= r; i++, j++) {
29
        q[i] = tmp[j];
30
    }
31
}
32

33
int main() {
34
    scanf("%d", &n);
35
    for (int i = 0; i < n; i++) scanf("%d", &q[i]);
36

37
    merge_sort(q, 0, n - 1);
38

39
    for (int i = 0; i < n; i++) printf("%d ", q[i]);
40
    return 0;
41
}

展开收起

5、为什么归并排序稳定#

看这句：

1
if (q[i] <= q[j]) tmp[k++] = q[i++];

当左右两个数相等时，先放左边的元素。这样相等元素的原始相对顺序不会被打乱，所以归并排序是稳定排序。

6、复杂度#

每一层合并所有元素，总共是 O(n)。

数组每次二分，层数是 O(log n)。

所以总时间复杂度：

1
O(n log n)

额外空间复杂度：

1
O(n)

因为需要临时数组 tmp。

7、容易写错的地方#

（1）递归右区间从 `mid + 1` 开始#

1
merge_sort(q, mid + 1, r);

不要写成 merge_sort(q, mid, r)，否则区间可能无法缩小。

（2）剩余元素要继续复制#

1
while (i <= mid) tmp[k++] = q[i++];
2
while (j <= r) tmp[k++] = q[j++];

两个区间不一定同时走完。

（3）最后要复制回原数组#

1
q[i] = tmp[j];

如果忘了这一步，递归上一层拿到的还是旧数组。

总结#

归并排序可以记成：

1
二分 -> 排左边 -> 排右边 -> 合并两个有序区间

它的模板比快速排序更稳定，也更适合继续扩展到“逆序对数量”等问题。

DataFrame

Sun, 28 Sep 2025 05:50:43 GMT

DataFrame学习#

DataFrame基本介绍#

在 pandas 中，DataFrame 是一种二维表格型数据结构，可以理解为 “带标签的二维数组” 或 “多个 Series 的组合”。它具有行索引（index）和列索引（columns），能够存储不同数据类型的列（如整数、字符串、日期等），是 pandas 中最核心、最常用的数据结构，广泛用于数据分析、清洗和处理。如果把 Series 比作 “带标签的一列数据”，那么 DataFrame 就是 “带标签的多列数据组成的表格”。例如：

姓名	年龄	城市
张三	25	北京
李四	30	上海
王五	28	广州

这就是一个简单的 DataFrame，其中 “姓名"" 年龄 ""城市” 是列索引，每行的索引默认为 0、1、2（也可自定义）。

DataFrame的创建#

1
# dataframe的创建方式
2
import pandas as pd
3
import numpy as np
4
# 通过series来创建
5
s1 = pd.Series([1,2,3,4,5])
6
s2 = pd.Series([6,7,8,9,10])
7
df = pd.DataFrame({"第1列":s1,"第2列":s2})
8
# 通过字典来创建
9
df = pd.DataFrame(
10
    {
11
        "name":["tom",'jack','alice','bob','allen'],
12
        "age":[15,17,20,26,30],
13
        "score":[60.5,80,30.6,70,83.5]
14
    },index=[1,2,3,4,5],columns=["name","score","age"]
15
)
16
df

展开收起

DataFrame的属性#

DataFrame的常用方法#

1
'''
2
案例1：学生成绩分析
3
场景：某班级的学生成绩数据如下，请完成以下任务：
4
1. 计算每位学生的总分和平均分。
5
2. 找出数学成绩高于90分或英语成绩高于85分的学生。
6
3. 按总分从高到低排序，并输出前3名学生。
7
'''
8
import pandas as pd
9
data = {
10
    '姓名': ['张三', '李四', '王五', '赵六', '钱七'],
11
    '数学': [85, 92, 78, 88, 95],
12
    '英语': [90, 88, 85, 92, 80],
13
    '物理': [75, 80, 88, 85, 90]
14
}
15
scores = pd.DataFrame(data)
16

17
#1. 计算每位学生的总分和平均分。
18
scores['总分'] = scores[['数学','英语','物理']].sum(axis=1)
19
scores['平均分'] = scores['总分'] / 3
20
scores['平均分2'] = scores[['数学','英语','物理']].mean(axis=1)
21
#2. 找出数学成绩高于90分或英语成绩高于85分的学生。
22
scores[ (scores['数学']>90 ) | (scores['英语']>85 )  ]
23
#3. 按总分从高到低排序，并输出前3名学生。
24
r1 = scores.sort_values('总分',ascending=False).head(3)
25
r2 =scores.nlargest(3,columns=['总分'])
26
print(r1)
27
print(r2)

展开收起

1
'''
2
案例2：销售数据分析
3
场景：某公司销售数据如下，请完成以下任务：
4
1. 计算每种产品的总销售额（销售额 = 单价 × 销量）。
5
2. 找出销售额最高的产品。
6
3. 按销售额从高到低排序，并输出所有产品信息。
7
'''
8
import pandas as pd
9

10
data = {
11
    '产品名称': ['A', 'B', 'C', 'D'],
12
    '单价': [100, 150, 200, 120],
13
    '销量': [50, 30, 20, 40]
14
}
15
df = pd.DataFrame(data)
16
df['总销售额'] = df['单价']*df['销量']
17
df.nlargest(1,columns=['总销售额'])
18
df.sort_values('总销售额',ascending=False)

展开收起

1
'''
2
案例3：电商用户行为分析
3
场景：某电商平台的用户行为数据如下，请完成以下任务：
4
1. 计算每位用户的总消费金额（消费金额 = 商品单价 × 购买数量）
5
2. 找出消费金额最高的用户，并输出其所有信息
6
3. 计算所有用户的平均消费金额（保留2位小数）
7
4. 统计电子产品的总购买数量
8
'''
9
import pandas as pd
10

11
data = {
12
    '用户ID': [101, 102, 103, 104, 105],
13
    '用户名': ['Alice', 'Bob', 'Charlie', 'David', 'Eve'],
14
    '商品类别': ['电子产品', '服饰', '电子产品', '家居', '服饰'],
15
    '商品单价': [1200, 300, 800, 150, 200],
16
    '购买数量': [1, 3, 2, 5, 4]
17
}
18
df = pd.DataFrame(data)
19
df['总消费金额'] = df['商品单价']*df['购买数量']
20
df.nlargest(1,columns=['总消费金额'])
21
df['总消费金额'].mean()
22
df[df['商品类别']=='电子产品']['购买数量'].sum()

展开收起

快速排序

Sat, 27 Sep 2025 15:37:23 GMT

快速排序#

快速排序是分治思想里很经典的一类排序。它的核心不是“直接把整个数组排好”，而是先选一个分界值，把数组分成两边：

左边的数都不大于分界值。
右边的数都不小于分界值。
然后递归处理左右两段。

这样每一层都把问题拆小，直到区间里只剩一个数，整个数组自然就有序了。

1、适合解决什么问题#

给定一个数组，要求从小到大排序：

1
5 3 8 4 2

排序后得到：

1
2 3 4 5 8

快速排序通常用于普通数组排序，平均时间复杂度是 O(n log n)，代码也比较短。

2、快速排序的基本步骤#

1
1. 选择一个分界值 x
2
2. 用两个指针 i、j 从区间两端向中间走
3
3. i 找到左边第一个 >= x 的数
4
4. j 找到右边第一个 <= x 的数
5
5. 如果 i < j，就交换 q[i] 和 q[j]
6
6. 划分完成后，递归排序左区间和右区间

这里最重要的是第 2 步到第 5 步，也就是“调整区间”。

3、双指针划分过程#

假设数组是：

1
5 3 8 4 2

选中间值 8 作为分界值时，左指针从左往右找不该在左边的数，右指针从右往左找不该在右边的数。

真正写模板时，我们不需要把每一步都手动模拟，只要记住这一点：

1
i 往右找 >= x 的数
2
j 往左找 <= x 的数
3
找到后交换

循环结束后，j 左边是一段，j + 1 右边是一段。

4、C++ 模板#

1
#include <bits/stdc++.h>
2
using namespace std;
3

4
const int N = 1000010;
5

6
int n;
7
int q[N];
8

9
void quick_sort(int q[], int l, int r) {
10
    if (l >= r) return;
11

12
    int x = q[(l + r) >> 1];
13
    int i = l - 1;
14
    int j = r + 1;
15

16
    while (i < j) {
17
        do i++; while (q[i] < x);
18
        do j--; while (q[j] > x);
19
        if (i < j) swap(q[i], q[j]);
20
    }
21

22
    quick_sort(q, l, j);
23
    quick_sort(q, j + 1, r);
24
}
25

26
int main() {
27
    scanf("%d", &n);
28
    for (int i = 0; i < n; i++) scanf("%d", &q[i]);
29

30
    quick_sort(q, 0, n - 1);
31

32
    for (int i = 0; i < n; i++) printf("%d ", q[i]);
33
    return 0;
34
}

展开收起

5、为什么递归区间是 `[l, j]` 和 `[j + 1, r]`#

这套模板使用的是 Hoare 划分方式。循环结束时，j 是左半部分的最后一个位置，所以继续递归：

1
quick_sort(q, l, j);
2
quick_sort(q, j + 1, r);

不要把它随便改成 [l, i - 1] 和 [i, r]，除非整套划分写法也一起换。

6、容易写错的地方#

（1）`l + r >> 1` 最好加括号#

1
int x = q[(l + r) >> 1];

虽然位运算优先级可以记住，但加括号更清楚。

（2）递归出口不能漏#

1
if (l >= r) return;

没有出口会无限递归。

（3）两个 do-while 的方向不能反#

1
do i++; while (q[i] < x);
2
do j--; while (q[j] > x);

一个从左往右，一个从右往左，分别找需要交换的位置。

总结#

快速排序可以记成：

1
选分界值 -> 双指针划分 -> 递归左右两边

真正难点不是递归，而是理解双指针为什么能把小数放左边、大数放右边。把这一点想清楚，模板就比较好背了。

建站宣言

Thu, 11 Sep 2025 15:26:04 GMT

TJC工作站

Firefly 博客示例功能合集

Firefly 一款清新美观的 Astro 博客主题模板#

🌟 项目概述#

🚀 技术架构#

📖 配置说明#

Firefly 简单使用指南#

文章的 Front-matter#

文章文件的放置位置#

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 使用示例#

示例 1：使用文件名作为 URL#

示例 2：自定义 Slug#

示例 3：其他语言文件名使用Slug#

Slug 使用建议#

注意事项#

Firefly 布局系统详解#

📖 概述#

一、侧边栏布局系统#

1.1 单侧边栏模式#

左侧边栏 (position: “left”)#

右侧边栏 (position: “right”)#

特点#

适用场景#

配置示例#

1.2 双侧边栏模式 (position: “both”)#

特点#

布局结构#

适用场景#

配置示例#

二、文章列表布局系统#

2.1 列表模式 (defaultMode: “list”)#

特点#

列表布局结构#

优点#

配置示例#

2.2 网格模式 (defaultMode: “grid”)#

特点#

自适应网格#

配置示例#

2.3 瀑布流布局 (Masonry)#

三、布局组合指南#

四、响应式布局行为#

五、常见问题#

Q1: 如何调整网格列数？#

六、总结#

相关链接#

Markdown 教程#

块级元素#

段落与换行#

段落#

换行#

标题#

Setext#

This is an H1#

This is an H2#

atx#

This is an H1#

This is an H2#

This is an H6#

This is an H1#

This is an H2#

This is an H3#

引用#

This is a header.#

列表#

无序列表#

有序列表#

列表中的缩进内容#

列表项里的引用#

列表项里的代码块#

嵌套列表#

代码块#

围栏代码块#

语法高亮#

分割线（水平线）#

表格#

内联元素#

链接#