Rice-awa's Blog

2026年AI驱动：10分钟快速搭建个人网站全攻略（GitHub Pages + Vercel）

Mon, 06 Apr 2026 00:00:00 GMT

一、引言：现在搭个人网站，真的不用懂太多编程#

放在两年前，我还觉得搭个人网站是开发者的专属技能，自己对着代码敲半天，还总出bug。但到了2026年，情况完全不一样了——借助AI编程助手，比如Claude code、Cursor、Qoder这些，就算你不是技术出身，也能快速生成可用的网站代码；再配合GitHub Pages和Vercel这两个免费平台，从头到尾10分钟，就能把网站部署上线，全程不用碰复杂的服务器配置。

我总结了一套简易的流程，下面分三大模块讲解：

GitHub Pages：部署单HTML文件，适合极简个人主页
Vercel：部署现代前端框架（Next.js/React/Vue），适合功能丰富的个人网站
AI辅助：用AI编程助手快速生成网站代码，降低开发门槛

二、方案一：GitHub Pages 部署单HTML文件（极简入门）#

GitHub Pages 是GitHub提供的免费静态网站托管服务，完全免费、无需服务器、操作简单，我使用它最大的感受就是“省心、免费、不用折腾”。它适合做那种内容简单的静态页面，比如个人简历、简单的作品集展示，不用复杂的交互功能。成品预览（你可以直接fork我这个项目）:Luminary — 一个关于思考与写作的地方

2.1 核心优势与限制#

优势	限制
✅ 永久免费，无广告	❌ 仅支持纯静态页面，无后端能力
✅ 与GitHub生态深度集成，版本管理便捷	❌ 国内访问稳定性一般，流量/存储有限（1GB存储/100GB流量/月）
✅ 支持自定义域名，配置简单	❌ 无Serverless功能，复杂交互需前端实现

2.2 详细部署步骤（单HTML文件）#

步骤1：准备工作#

注册GitHub账号（Sign up for GitHub），完成邮箱验证
本地安装Git（Git），配置用户信息：

Terminal window

1
git config --global user.name "你的GitHub用户名"
2

3
git config --global user.email "你的GitHub注册邮箱"

步骤2：创建GitHub仓库#

登录GitHub，点击右上角「+」→「New repository」
仓库名称必须为：<你的用户名>.github.io（例如：rice-awa.github.io），确保勾选「Public」（公共仓库）
点击「Create repository」完成创建

步骤3：编写并上传HTML文件#

克隆仓库到本地：

Terminal window

1
git clone https://github.com/<你的用户名>/<你的用户名>.github.io.git
2

3
cd <你的用户名>.github.io

创建极简个人主页index.html（可直接复制使用，或用AI生成优化）：

1
<!DOCTYPE html>
2

3
<html lang="zh-CN">
4

5
<head>
6

7
<meta charset="UTF-8">
8

9
<title>我的个人主页</title>
10

11
<style>
12

13
body { font-family: Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 2rem; text-align: center; }
14

15
h1 { color: #2c3e50; }
16

17
.intro { color: #34495e; line-height: 1.6; margin: 2rem 0; }
18

19
</style>
20

21
</head>
22

23
<body>
24

25
<h1>欢迎来到我的2026个人主页</h1>
26

27
<div class="intro">
28

29
<p>AI驱动的快速建站实践 | 技术探索者 | 2026马年大吉</p>
30

31
<p>GitHub: <a href="https://github.com/<你的用户名>" target="_blank">点击访问</a></p>
32

33
</div>
34

35
</body>
36

37
</html>

显示更多显示更少

上传代码到GitHub：

Terminal window

1
git add .
2

3
git commit -m "Initial commit: 个人主页HTML"
4

5
git push origin main

步骤4：开启GitHub Pages部署#

进入仓库页面，点击顶部「Settings」→ 左侧「Pages」
「Source」选择「Deploy from a branch」，「Branch」选择「main」+「/ (root)」，点击「Save」
等待1-2分钟，访问 https://<你的用户名>.github.io 即可看到个人主页

2.3 进阶：使用gh-pages分支部署（多页面场景）#

若需添加多个页面（如博客、项目展示），可创建gh-pages分支部署：

Terminal window显示更多显示更少

1
# 创建并切换到gh-pages分支
2

3
git checkout --orphan gh-pages
4

5
git rm -rf . # 清空当前分支文件
6

7
# 编写多页面代码后提交
8

9
git add .
10

11
git commit -m "Add multi-page content"
12

13
git push origin gh-pages
14

15
# 回到Settings → Pages，将Branch改为gh-pages

显示更多显示更少

三、方案二：Vercel 部署现代前端框架（功能进阶）#

如果觉得GitHub Pages功能太简单，想做一个有交互、有多个页面的个人网站，比如个人博客、作品集展示站，那Vercel绝对是首选。我现在的个人博客就是用Vercel部署的，最大的感受是“零配置、速度快”，它是很多现代前端框架官方推荐部署平台的部署平台，支持零配置部署React、Vue、Svelte、Astro等主流框架，提供全球CDN加速、自动CI/CD、预览环境等高级功能。

3.1 核心优势与限制#

优势	限制
✅ 零配置部署，自动识别框架并配置构建命令	❌ 免费版有额度限制（构建次数/月），超出需付费
✅ 全球70+边缘节点，访问速度快，支持SSR/SSG	❌ 国内网络访问需特殊配置（可通过Cloudflare + 自定义域名解决）
✅ 支持Serverless函数，可实现简单后端功能
✅ 自动部署，提交代码即更新，支持预览环境

3.2 详细部署步骤（以Next.js为例）#

步骤1：初始化现代前端项目（可AI生成）#

安装Node.js 18+（https://nodejs.org/）
初始化Next.js项目（用AI助手可自动生成模板）：

Terminal window

1
npx create-next-app@latest my-personal-site
2

3
cd my-personal-site

本地运行测试：npm run dev，访问http://localhost:3000 查看效果

步骤2：关联GitHub仓库#

将项目推送到GitHub（先在GitHub创建空仓库my-personal-site）：

Terminal window

1
git init
2

3
git add .
4

5
git commit -m "Initial Next.js project"
6

7
git branch -M main
8

9
git remote add origin https://github.com/<你的用户名>/my-personal-site.git
10

11
git push -u origin main

步骤3：Vercel部署全流程#

注册Vercel账号（Verce），推荐用GitHub账号登录（自动授权）
登录后点击「New Project」→「Import Git Repository」，选择刚创建的my-personal-site仓库
项目配置（自动识别Next.js框架，无需手动修改）：

「Framework Preset」：自动选择「Next.js」
「Build Command」：自动填充next build
「Output Directory」：自动填充.next
「Project Name」：自定义（如my-personal-site）

点击「Deploy」，等待1-3分钟部署完成
访问Vercel提供的默认域名（如https://my-personal-site-<你的用户名>.vercel.app）即可看到网站

3.3 其他框架部署要点#

React（Vite）：初始化npm create vite@latest my-react-site -- --template react，Vercel自动识别
Vue（Nuxt）：初始化npx nuxi init my-nuxt-site，Vercel支持零配置部署
纯HTML/CSS/JS：直接上传到GitHub，Vercel可导入仓库并部署

四、AI辅助：用编程助手快速生成与搭建网站#

2026年，AI编程助手已成为建站核心工具，无需手写基础代码，通过对话即可生成符合需求的网站结构、样式与交互逻辑，大幅降低开发门槛。

4.1 主流AI编程助手选型（2026最新）#

工具	特点	适用场景
Cursor	集成Claude 4.6 Sonnet，代码生成质量高，支持本地项目上下文	复杂个人网站、自定义交互
Qoder	阿里出品，中文支持优秀，免费额度充足，适配国内环境	国内用户、快速原型开发

4.2 实操：用Cursor生成个人网站代码#

步骤1：准备提示词（Prompt）#

打开Cursor，输入以下提示词（可根据需求修改），建议配合以下4.3 高效前端设计Skills（通用，来自Claude网页端）使用：

1
你是一位资深前端开发工程师，帮我生成一个**极简个人主页**的完整代码，要求如下：
2

3
1. 技术栈：纯HTML + CSS + JS，无需框架，适配移动端
4

5
2. 页面结构：导航栏（首页、关于、项目、联系）、个人简介区、技能展示、页脚
6

7
3. 样式要求：2026马年主题，简约大气。
8

9
4. 交互：导航栏吸顶，技能卡片hover效果，平滑滚动
10

11
5. 内容：包含我的GitHub链接、AI编程助手使用心得
12

13
6. 输出：完整的index.html文件，包含所有CSS和JS，代码注释清晰
14

15
7. **遵循以下frontend-design skill（如果有）**

显示更多显示更少

步骤2：优化与调整#

Cursor会生成完整代码，可直接复制到本地项目
若需修改，可继续对话调整：「把技能展示区改为卡片布局，添加马年图标」「修改导航栏为透明背景，滚动时变色」
用AI助手生成代码后，可直接上传到GitHub Pages或提交到Vercel项目仓库，一键部署

步骤3：AI+部署全流程加速#

用Qoder生成个人网站代码 → 保存为index.html
用Git上传到GitHub Pages仓库 → 开启Pages部署
或直接导入Vercel → 自动部署，全程无需手动编写复杂代码

4.3 高效前端设计Skills（通用，来自Claude网页端）#

1
---
2
name: frontend-design
3
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
4
---
5

6
`This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.`
7

8
`The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.`
9

10
`## Design Thinking`
11

12
`Before coding, understand the context and commit to a BOLD aesthetic direction:`
13

14
`- **Purpose**: What problem does this interface solve? Who uses it?`
15

16
`- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.`
17

18
`- **Constraints**: Technical requirements (framework, performance, accessibility).`
19

20
`- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?`
21

22
`**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.`
23

24
`Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:`
25

26
`- Production-grade and functional`
27

28
`- Visually striking and memorable`
29

30
`- Cohesive with a clear aesthetic point-of-view`
31

32
`- Meticulously refined in every detail`
33

34
`## Frontend Aesthetics Guidelines`
35

36
`Focus on:`
37

38
`- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.`
39

40
`- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.`
41

42
`- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.`
43

44
`- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.`
45

46
`- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.`
47

48
`NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.`
49

50
`Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.`
51

52
`**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.`
53

54
`Remember: You is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.`

显示更多显示更少

五、GitHub Pages vs Vercel 终极对比（2026版）#

对比维度	GitHub Pages	Vercel	选择建议
成本	完全免费，无任何费用	免费版有额度限制，高级功能付费	纯静态页面选GitHub Pages；需高级功能选Vercel
部署难度	简单，需手动配置分支/域名	零配置，自动识别框架，一键部署	新手选Vercel；追求极致免费选GitHub Pages
性能	国内访问不稳定，CDN覆盖有限	全球70+边缘节点，访问速度快	面向全球用户选Vercel；国内用户可搭配Cloudflare
功能支持	仅纯静态页面，无后端能力	支持SSR/SSG/Serverless，功能丰富	需后端/动态功能选Vercel；仅展示选GitHub Pages
生态集成	与GitHub深度集成，版本管理强	与前端框架（Next.js/Vue/React）官方集成	框架项目选Vercel；纯HTML选GitHub Pages
自定义域名	支持，免费SSL证书	支持，免费SSL证书，配置更灵活	两者均可，按需选择

六、总结与下一步#

2026年搭建个人网站已进入**“AI生成+一键部署”的零门槛时代**：

若你追求极简、免费、稳定，选GitHub Pages，10分钟内完成单HTML页面部署
若你需要功能丰富、高性能、框架适配，选Vercel，零配置部署现代前端项目
若你是非技术人员，用AI编程助手也能快速生成代码，再配合部署平台，无需编程基础也能拥有专业个人网站

最后给大家一个下一步建议，搭完网站后可以做这几件事，让网站更专业：

用 AI 生成个性化网站内容（如个人简介、项目展示）。
绑定自定义域名，GitHub Pages和Vercel都支持，选一个好记的域名，显得更专业，免费SSL证书一定要配置，保证访问安全。
持续更新网站内容，比如定期添加项目、写点心得，也可以用AI工具优化网站体验，比如添加AI聊天助手、智能搜索功能。

开发第一步--2026最新集成开发环境配置全指南

Fri, 13 Mar 2026 00:00:00 GMT

开发第一步：2026最新集成开发环境配置全指南#

编程的第一步，永远是搭好趁手的开发环境。选错工具、配置踩坑，会直接消耗学习与开发的热情。本文基于2026年最新工具版本，覆盖传统主流IDE与AI原生IDE，按场景推荐、分步骤配置，新手也能一次成功。

一、开发场景与编辑器推荐（直接抄作业）#

先按你的开发语言/方向选工具，不盲目安装：

开发场景	推荐IDE/编辑器	核心优势
Java 后端开发	IntelliJ IDEA	JVM生态最优、重构/调试最强
Python 开发（AI/数据分析/后端）	PyCharm	专业Python支持、虚拟环境一键管理
C/C++ 开发	CLion	跨平台编译、CMake原生支持
前端开发（Vue/React/小程序）	VSCode	轻量、插件生态无敌、启动快
Go 语言开发	GoLand	语法提示、工程化工具完善
全栈/多语言快速切换	VSCode	一套配置通吃所有语言
AI 辅助开发（快速生成/调试）	Cursor / Trae	AI原生、自然语言编程、零配置
命令行+轻量AI编程	Qoder CLI	低内存、终端友好、自动化任务

二、传统主流IDE详解与基础安装#

1. JetBrains 全家桶（专业级一站式IDE）#

JetBrains是专业开发者的首选，一套操作逻辑通吃所有语言，2026年已全面内置AI助手。

产品定位速览#

IntelliJ IDEA：Java/Kotlin/后端（社区版免费）
PyCharm：Python/AI/数据分析（社区版免费）
CLion：C/C++/Rust
WebStorm：前端/Node.js
GoLand：Go语言
DataGrip：数据库/SQL

安装与通用配置#

官网下载对应IDE：https://www.jetbrains.com/zh-cn/
安装：默认路径 → 勾选添加到PATH → 完成
通用优化（所有JB IDE通用）：
- 外观：Settings → Appearance → 主题选Darcula/新UI
- 字体：Editor → Font → 推荐JetBrains Mono，字号14-16
- 自动保存：取消Safe Write，开启自动保存
- AI助手：2026版自带JetBrains AI，免费基础功能可用

2. VSCode（轻量全能王者）#

免费开源、跨平台、插件无限扩展，是新手与全栈开发者首选。

安装步骤#

官网下载：https://code.visualstudio.com/
安装必勾选项：
- 添加到PATH
- 资源管理器中通过VSCode打开文件/文件夹
初始化：安装中文（简体）语言包 → 重启生效

三、2026 AI原生IDE/编程助手#

AI正在重构开发工具，以下三款是当前最稳定、好用的AI IDE：

1. Cursor（AI IDE标杆，基于VSCode魔改）#

定位：全工程AI理解、自动重构、Agent自动执行
优势：兼容VSCode插件、双模型（GPT-4o+Claude 3.5）、本地索引
安装：https://www.cursor.com/ → 一键安装 → 登录即可用

2. Trae（字节跳动AI原生IDE，中文友好）#

定位：国内开发者首选、免费、中文自然语言编程
优势：全中文界面、草图转代码、语音指令、零门槛
安装：https://www.trae.com.cn/ → 向导式安装，无需配置

3. Qoder（阿里AI编程工具，CLI+IDE双模式）#

定位：轻量、自动化、终端友好
安装CLI：

Terminal window

1
npm install -g @qoder-ai/qodercli
2
qodercli --version # 验证安装

四、详细环境配置教程（新手零失败）#

🔧 VSCode 配置 C++ 开发环境（Windows/macOS/Linux）#

步骤 1：安装编译器（必装）

先下载别人已经构建好的 Mingw releases版
Windows：安装 MinGW-w64 → 解压到自定义路径D:\mingw64（无中文 / 空格 / 特殊字符）
macOS：xcode-select --install
Linux：sudo apt install g++ gcc gdb

步骤 2：配置系统环境变量（Windows）

此电脑 → 属性 → 高级系统设置 → 环境变量
系统变量 → Path → 新增：D:\mingw64\bin
验证：终端输入g++ --version → 显示版本即成功

步骤 3：VSCode 插件安装

C/C++（微软官方）
CodeLLDB（调试增强）
C/C++ Extension Pack

步骤 4：项目配置（自动生成）

新建文件夹 → 用 VSCode 打开
新建main.cpp，写测试代码：

1
#include <iostream>
2
using namespace std;
3
int main() {
4
    cout << "Hello C++ VSCode" << endl;
5
    return 0;
6
}

按Ctrl+Shift+P → 输入Tasks: Configure Task → 选g++.exe build
按F5调试 → 自动生成launch.json/tasks.json，直接运行

🔧 VSCode 配置 Python 开发环境#

安装 Python：官网下载 → 勾选Add to PATH
必装插件：
- Python（微软官方）
- Pylance（智能提示）
- Black Formatter（格式化）
- isort（导入排序）
配置虚拟环境：
- Ctrl+Shift+P → Python: Create Environment → 选 venv
- 选择 Python 版本 → 自动创建隔离环境

🔧 PyCharm 配置 Python 环境#

安装 PyCharm 社区版（免费）
新建项目：
- 选择 Pure Python
- 选择 New Virtual Environment
- 指定 Python 解释器路径
运行测试：新建.py文件 → 右键运行

🔧 AI IDE 基础配置（Cursor/Trae）#

插件同步：Cursor 直接导入 VSCode 插件
模型选择：
- Cursor：设置 → Model → 选 Claude 3.5/GPT-4o
- Trae：中文优选 DeepSeek R1 / 豆包 1.5 Pro
快捷键：
- Cursor：Ctrl+I唤起 AI 生成
- Trae：Ctrl+K快速指令

五、常见问题与避坑指南#

环境变量不生效：配置后必须重启终端 / VSCode
C++ 编译报错：检查编译器路径是否为g++.exe（不是 gcc）
Python 找不到解释器：重新选择解释器路径，确保 Add to PATH
AI IDE 联网失败：关闭代理，或切换模型为国内节点
JetBrains IDE 卡顿：调低内存占用，关闭不必要的插件

六、总结#

新手 / 轻量开发：VSCode 通吃所有场景
专业单语言：JetBrains 对应 IDE（PyCharm/IDEA/CLion）
AI 提效：Cursor（专业）/ Trae（中文免费）
环境配置核心：编译器 + 环境变量 + 核心插件三件套

开发环境是第一步，搭好之后，就可以专心写代码了。

2026年AI编程助手：一场静悄悄的革命

Sun, 15 Feb 2026 00:00:00 GMT

如果你现在还在自己手写代码，那可能要重新考虑一下了。

到 2025 年，AI 编程工具已经从“尝鲜”变成“默认”。Stack Overflow 2025 开发者调研显示，84% 的开发者已经在使用或计划使用 AI 工具参与开发流程，其中专业开发者有超过一半是每天在用。

数字当然重要，但更关键的变化不在数字上，而在于——我们到底把 AI 当成什么。

现在的AI，不只是补全代码#

早期的 AI 编程助手干的活很单纯：
你写一行，它帮你补全下一行。

现在的局面已经完全不一样了。

Claude Code、Codex、Cursor 这类工具，已经可以理解整个代码库，自己跑测试，自己迭代修改，甚至能同时改几十个文件然后告诉你改了什么。

开发者社区讨论的重心也变了：

以前是——

AI 能不能帮我写代码？

现在更像是——

AI 能不能帮我干完一整票活？

这背后，是产品形态的变化：

从 assistant（助手）
走向 agent（智能体）

助手是你说什么它做什么。
智能体是你告诉它目标，它自己拆任务、找路径、调用工具、一步步推进，直到接近可交付结果。

这不是功能升级，是角色变化。

2026年，谁在牌桌上？#

说了这么多，到底哪些工具值得关注？

Cursor：最顺手的“默认选项”#

很多人用 Cursor，不是因为它最强，而是因为它最顺。

聊天窗口嵌在编辑器里，小到修个 bug，大到中等规模重构，它都能 handle。

缺点也明显：
复杂的长流程任务偶尔会犯傻，在一个地方反复打转。

它是高频使用的那一个。

Claude Code：关键时刻能托付#

遇到真正棘手的问题——

完全陌生的大型代码库
难以复现的隐蔽逻辑错误
复杂架构推理

很多人会更信 Claude。

它更像那个“关键时刻能托付”的角色，而不是日常打下手的助手。

代价也摆在那里：成本与速率限制，是现实问题。

Codex：强调确定性的独立 Agent#

OpenAI 这两年把 Codex 往“真正独立 agent”方向推进。

它的优点是确定性强——
多步骤任务通常能一步步完成，不容易跑偏。

适合那种“我希望你按流程执行完”的场景。

GitHub Copilot：它就在那儿#

Copilot 的优势在于：

它就在那儿
审批更容易
企业接受度高

虽然在深度 agent 能力上未必最强，但在现实世界里，“省心”本身就是竞争力。

Cline：控制欲玩家的乐园#

Cline 让你：

自己选模型
自己调上下文
自己决定 AI 什么时候介入

它更灵活，也更折腾。

适合愿意花时间打磨工作流的人。

Windsurf：路线比功能更重要#

Windsurf 经历过一段戏剧性的收购风波，最终被 Cognition 收购其产品与 IP。

产品体验依然精致，但开发者真正关心的是：

它未来会走向哪里？

在 agent 时代，路线比功能更重要。

国内玩家：这桌牌，已经坐满了#

如果你面向的是中文开发者或国内企业环境，以下这些工具绕不开。

Qoder（阿里云）#

国内覆盖面很广的一档产品。

除了代码补全与问答，也在强调“编程智能体”能力，包括：

工程级上下文理解
多文件编辑
命令行协助
单测生成

在企业落地和合规环境里优势明显。

腾讯云代码助手 CodeBuddy#

更强调“全流程智能研发”叙事。

从需求构思到代码实现再到发布协作，偏平台化整合路线。

TRAE（AI 原生 IDE）#

更激进的方向。

主打 AI 原生 IDE + SOLO 模式，希望让智能体主导完整开发流程。

它代表的是一种趋势：

不是“AI 嵌入 IDE”，
而是“IDE 围绕 AI 重构”。

豆包 MarsCode#

字节推出的 AI IDE + 插件体系。

支持：

代码生成
解释重构
单测生成
错误修复

覆盖主流 IDE，增长速度很快。

文心快码（Baidu Comate）#

百度基于文心大模型推出的编程助手。

功能齐全：

代码生成
单元测试生成
注释补全
问答解释

主打“更懂中文语境的开发”。

华为 CodeArts 盘古助手 / DevEco CodeGenie#

偏平台内生态整合路线。

在企业研发平台和鸿蒙开发环境内嵌 AI 能力：

问答
代码生成
调试优化
单测辅助

优势在于生态绑定和企业部署能力。

iFlyCode（科大讯飞）#

基于星火大模型。

强调从编码到测试的全流程提效，并提供企业级定制与私有部署选项。

一句话总结：

国外工具跑在交互形态与模型能力前沿
国内工具在合规、企业部署、中文语境与生态整合上更贴地

大家现在真正关心什么？#

社区讨论的风向已经变了。

以前比谁更聪明。
现在比谁更省钱。

Token 效率 = 成本。
每一次 hallucination，都是在烧预算。

除了成本，开发者最在乎的还有三件事：

1️⃣ 代码质量#

写得快不重要。
重要的是写得对、好维护、不埋坑。

2️⃣ 上下文理解能力#

能不能真正“看懂整个项目”？

在大型工程里，这一点决定体验差异。

3️⃣ 隐私与合规#

代码去了哪里？
是否参与训练？
企业是否允许云端使用？

很多公司因此选择：

私有化部署
国产模型
平台内嵌方案

新玩家仍在冒头#

Spec-driven 与 Agent-first 正在成为新方向。

先定义规格，再由 AI 自动推进实现。

这类工具还在早期，但值得关注。

尾声#

没有完美的 AI 编程工具。

Cursor 用着省心，但深度有限
Claude 深度够，但成本高
Copilot 最无感，但高级能力有限
Cline 最灵活，但需要自己折腾
国内工具企业落地强，但前沿玩法有时慢半拍

真正重要的问题不是：

哪个最强？

而是：

你要什么？

要速度还是控制？
要省心还是深度？
要极限能力还是稳定合规？

我的建议是：先想清楚自己要什么。要速度还是要控制？要省心还是要深度？然后去试，别只看评测。自己用一周，比看十篇对比文章都管用。这场革命静悄悄的，但它已经发生了。 84%的数字不会骗人。

Minecraft Java 版服务端管理协议（MSMP）开发者使用文档

Wed, 11 Feb 2026 00:00:00 GMT

文档版本：2026-02-11
协议版本：2.0.0 / 1.21.11+
目标读者：插件开发者、服务器管理工具开发者、托管平台集成工程师

1. 协议概览与核心概念#

1.1 协议定位与设计目标#

Minecraft 服务端管理协议（Minecraft Server Management Protocol，简称 MSMP）是 Mojang 为 Minecraft Java 版专用服务器（Dedicated Server）官方引入的原生管理 API，首次亮相于 2025 年 8 月 26 日发布的 25w35a 快照版本 。该协议的诞生填补了 Minecraft 服务器管理生态中长期存在的标准化缺口，为插件开发者、服务器托管平台以及自动化运维工具提供了一套标准化、实时化、双向交互的服务器管理能力。

在 MSMP 出现之前，Minecraft 服务器管理长期依赖三类方案，各有显著局限。RCON（Remote Console）协议作为官方提供的远程管理手段，基于 TCP 明文传输，仅支持单向命令发送与文本响应，存在严重的安全与功能缺陷：通信内容未经加密，认证机制简陋（单一密码明文传输），且无法获取结构化数据或实时事件。Query 协议专注于服务器状态查询，但仅提供只读信息，缺乏管理操作能力，且无认证机制。第三方 REST API 插件（如 MinecraftServerAPI 、DeveloperMCP 等）虽在一定程度上弥补了功能缺陷，却引入了生态碎片化问题——实现质量参差不齐、与特定服务端软件深度耦合、版本兼容性风险高、缺乏标准化保证。

MSMP 从根本上解决了上述问题。作为官方原生方案，它直接集成于服务端核心（server.jar），无需额外插件即可启用；遵循语义化版本控制的 API 演进策略，确保向后兼容性；通过命名空间机制预留扩展空间，允许第三方在标准框架内添加自定义方法与事件。协议采用 WebSocket 作为传输层协议，承载 JSON-RPC 2.0 格式的应用层消息，这一架构决策具有深远的工程意义：WebSocket 的全双工特性使得服务器能够在状态变更时主动向客户端推送通知，彻底改变了 RCON 时代”轮询查询”的低效模式；JSON-RPC 2.0 作为成熟的轻量级 RPC 规范，提供了清晰的请求-响应语义和标准化的错误处理机制，大幅降低了多语言客户端的开发门槛。

1.1.1 官方原生管理接口与第三方方案对比#

特性维度	MSMP	RCON	Query	第三方 REST API
传输协议	WebSocket (RFC 6455)	原始 TCP	UDP	HTTP/HTTPS
应用协议	JSON-RPC 2.0	自定义二进制	自定义二进制	REST/JSON
通信模式	双向全双工	单向请求-响应	单向请求-响应	单向请求-响应
实时通知	✅ 原生支持	❌ 不支持	❌ 不支持	⚠️ 需 Webhook/SSE
认证机制	40位密钥 + TLS + Origin 验证	明文密码	无认证	自定义（API Key/JWT）
加密传输	✅ TLS 原生支持	❌ 不支持	❌ 不支持	⚠️ 依赖 HTTPS
结构化数据	✅ JSON 强类型	纯文本解析	有限字段	通常 JSON
玩家管理	✅ 完整 CRUD	⚠️ 仅命令执行	❌ 仅查询	依赖插件实现
白名单管理	✅ 完整 CRUD	⚠️ 仅命令执行	❌ 不支持	依赖插件实现
管理员管理	✅ 完整 CRUD	⚠️ 仅命令执行	❌ 不支持	依赖插件实现
游戏规则修改	✅ 完整 CRUD	⚠️ 仅命令执行	❌ 不支持	依赖插件实现
服务端发现机制	✅ `rpc.discover`	❌ 无	❌ 无	依赖插件文档
官方维护	✅ 是	✅ 是	✅ 是	❌ 否
版本同步更新	✅ 保证	✅ 保证	✅ 保证	⚠️ 不确定

MSMP 在安全性、实时性、功能完整性三个维度均实现了对传统协议的全面超越。特别是在双向通信和实时通知方面，MSMP 的 WebSocket 基础架构提供了原生支持，而 RCON 和 Query 作为早期设计的协议，其单向通信模式从根本上限制了实时管理能力。第三方 REST API 方案虽然可以通过 Webhook 或长轮询模拟实时效果，但实现复杂度高且可靠性差。

1.1.2 基于 WebSocket + JSON-RPC 2.0 的双向通信架构#

MSMP 的通信架构由三个层次构成：传输层的 WebSocket 连接、消息格式的 JSON-RPC 2.0 封装，以及应用层的命名空间方法调度。WebSocket 连接建立后，客户端与服务端之间维持持久的全双工通道，所有管理操作与事件通知均在此通道上流转。相较于 HTTP 请求-响应模式，WebSocket 的长连接特性消除了频繁的 TCP 握手开销，将通信延迟降至最低；同时，服务端推送能力使得状态变更能够实时触达客户端，无需客户端主动轮询。

JSON-RPC 2.0 作为应用层协议，定义了两种消息类型：请求（Request）与通知（Notification）。请求消息包含唯一的 id 字段，服务端必须返回对应的响应（Response），形成完整的调用闭环；通知消息则无 id 字段，服务端不对其进行响应，适用于单向事件上报。这一区分对于客户端实现至关重要：开发者需为方法调用维护请求-响应映射表（通常以 id 为键），而为通知注册独立的事件处理器。混合处理这两种消息类型是常见的初学者错误，会导致响应匹配失败或通知丢失。

命名空间（Namespace）是 MSMP 方法组织的核心机制。所有标准方法均归属于 minecraft 命名空间，格式为 minecraft:<group>/<action>，如 minecraft:players（获取玩家列表）、minecraft:allowlist/add（添加白名单）。通知事件则采用 minecraft:notification/<event> 格式，如 minecraft:notification/players/joined（玩家加入事件）。这种层级化的命名策略既保证了方法的可发现性，又为未来的功能扩展预留了清晰的路径。

1.1.3 实时状态同步与事件驱动模型#

MSMP 的事件驱动模型是其相较传统方案的核心竞争力。在 RCON 时代，获取玩家加入事件的唯一方式是定期执行 list 命令并比对输出差异——这种轮询模式不仅消耗服务器资源，还存在显著的延迟（取决于轮询间隔）。MSMP 通过 minecraft:notification/players/joined 和 minecraft:notification/players/left 通知，将事件延迟降至网络传输极限（通常 <10ms），且零服务器端轮询开销。

事件驱动架构对插件开发范式产生了深远影响。以玩家管理插件为例，传统实现需维护定时任务扫描在线状态，而基于 MSMP 的实现则可完全事件化：注册通知处理器后，插件仅在事件触发时执行逻辑，资源占用与响应速度均获得数量级优化。更进一步，MSMP 的通知机制支持服务端状态的增量同步——当游戏规则（Gamerules）变更时，minecraft:notification/game-rules/updated 通知携带变更后的完整规则集，客户端无需重新查询即可更新本地缓存。

1.2 版本演进与兼容性#

1.2.1 引入版本：25w35a / 1.21.9+#

MSMP 于 2025 年 8 月 26 日随 25w35a 快照首次发布 ，随后在 1.21.9 正式版中稳定化。这一版本节点对于插件开发者具有重要参考价值：任何目标版本低于 1.21.9 的服务端均不支持 MSMP，需在文档中明确标注兼容性要求。值得注意的是，MSMP 的版本演进遵循独立于 Minecraft 主版本的语义化版本控制——rpc.discover 方法返回的 API 版本信息（如 2.0.0 (25w44a)）反映了协议本身的迭代状态，而非底层游戏版本。

开发者在实现客户端库时，应优先调用 rpc.discover 获取服务端支持的 API 版本与方法集合，而非硬编码假设。这一防御性编程策略能够适配未来可能的方法增删或行为变更。例如，mc-rpc Rust 库即基于运行时发现动态生成方法绑定，确保与任意支持 MSMP 的服务端版本兼容。

1.2.2 与 RCON、Query 等传统协议的功能对比#

功能场景	推荐协议	理由
实时玩家监控面板	MSMP	事件通知替代轮询，延迟低、开销小
自动化备份脚本	RCON	需要执行 `/save-all` 等任意命令
服务器列表网站展示	Query	无认证查询，UDP 穿透性好
第三方管理面板	MSMP	结构化 API，功能完整，安全性高
紧急故障恢复	RCON	不依赖 MSMP 服务状态，底层可靠
跨版本兼容工具	RCON/Query	协议稳定，长期支持

MSMP、RCON 和 Query 三种协议在功能定位上形成明显的互补关系，而非简单的替代关系。理解它们的差异有助于在不同场景下选择最合适的工具。

1.2.3 未来扩展性：命名空间预留与自定义扩展机制#

MSMP 的命名空间设计体现了前瞻性的扩展规划。除 minecraft（标准方法）和 notification（标准通知）两个保留命名空间外，协议明确允许第三方通过自定义命名空间添加方法与事件。这一机制为服务端软件（Fabric、Forge、Paper 等）以及插件框架提供了标准化的扩展通道：Fabric API 可通过 fabric:mods 命名空间暴露模组列表查询，Paper 可通过 paper:timings 命名空间集成性能分析数据，而无需破坏与标准客户端的兼容性。

对于插件开发者，自定义命名空间的采用需遵循以下最佳实践：命名空间应采用反向域名格式（如 com.example.myplugin）以避免冲突；自定义方法应复用标准模式中的类型定义（如 Player、Operator 对象）以保持接口一致性；文档中需明确标注扩展的最低服务端版本与依赖条件。

1.3 核心术语表#

1.3.1 命名空间（Namespace）：`minecraft` 与 `notification`#

命名空间是 MSMP 方法标识符的前缀段，用于逻辑分组与避免命名冲突。标准协议定义了两个保留命名空间：

命名空间	用途	格式示例
`minecraft`	承载所有管理操作方法	`minecraft:<group>/<action>`
`minecraft:notification/`	承载所有服务端主动推送的事件通知	`minecraft:notification/<event>`

minecraft 命名空间下的方法路径通常遵循 group/action 或 group/subgroup/action 的层级模式，例如 minecraft:players（获取玩家列表）、minecraft:allowlist/add（添加白名单）、minecraft:server/save（保存服务器）。这种层级设计使方法组织清晰，便于文档化和代码生成。

minecraft:notification/ 命名空间专用于服务端主动推送的事件通知。通知方法名同样采用层级结构，但语义侧重于状态变更而非操作指令，例如 minecraft:notification/players/joined（玩家加入）、minecraft:notification/players/left（玩家离开）、minecraft:notification/game-rules/updated（游戏规则更新）。通知与方法的命名空间分离，使客户端能够快速区分需要响应的请求和仅需处理的事件。

1.3.2 方法（Method）与通知（Notification）的区别#

特征	方法（Method）	通知（Notification）
消息方向	客户端 → 服务端	服务端 → 客户端
`id` 字段	必需（用于响应匹配）	必须省略
响应期望	服务端必须返回响应	无响应
典型用途	查询状态、执行操作	状态变更事件推送
错误处理	返回 `error` 对象	无（客户端本地处理）
MSMP 示例	`minecraft:players`	`notification:players/joined`

方法与通知的区分是 JSON-RPC 2.0 规范的核心语义，MSMP 严格遵循这一区分。开发者在实现客户端时，需为方法调用维护请求-响应映射表（通常以 id 为键），而为通知注册独立的事件处理器。

1.3.3 API 模式（Schema）与运行时发现机制#

MSMP 提供两种 API 模式获取方式，内容镜像一致但适用场景各异：

方式	获取时机	主要用途
`rpc.discover`	运行时	动态客户端适配，验证方法可用性
`json-rpc-api-schema.json`	构建时（数据生成器）	静态代码生成，离线文档构建

模式文件采用 JSON Schema 风格描述，包含方法参数、返回值、通知载荷的结构定义。以 operator 类型为例：

1
{
2
  "operator": {
3
    "properties": {
4
      "bypassesPlayerLimit": { "type": "boolean" },
5
      "permissionLevel": { "type": "integer" },
6
      "player": { "$ref": "#/components/schemas/player" }
7
    },
8
    "type": "object"
9
  }
10
}

运行时发现与静态生成的结合，使 MSMP 客户端能够在保证类型安全的同时，具备跨版本的适应能力。

2. 服务端配置与启用指南#

2.1 基础配置项详解#

MSMP 默认处于禁用状态，需通过 server.properties 文件显式启用。配置项的设计遵循”最小权限原则”与”安全优先原则”，所有涉及网络暴露的选项均提供细粒度的控制手段。

2.1.1 `management-server-enabled`：启用开关#

属性	值
配置键	`management-server-enabled`
数据类型	布尔值（`true`/`false`）
默认值	`false`
生效条件	服务端启动时读取

此为 MSMP 的总开关。设置为 true 后，服务端在启动时将初始化 WebSocket 服务器，监听配置的地址与端口。若保持默认 false，则 MSMP 相关代码完全不加载，零运行时开销。生产环境建议仅在需要管理功能时启用，以减少攻击面。

2.1.2 `management-server-host`：绑定地址（localhost/0.0.0.0）#

属性	值
配置键	`management-server-host`
数据类型	字符串（IP 地址或主机名）
默认值	`localhost`
典型值	`localhost`、`127.0.0.1`、`0.0.0.0`、具体公网 IP

绑定地址决定了 WebSocket 服务器的网络可见范围。localhost 或 127.0.0.1 仅允许本机连接，适用于管理工具与服务器同机部署的场景；0.0.0.0 绑定所有网络接口，允许远程连接，但必须配合 TLS 与严格认证以确保安全。云服务器部署时，建议显式指定内网 IP 而非 0.0.0.0，结合反向代理实现安全暴露。

2.1.3 `management-server-port`：端口设置（默认随机/静态指定）#

属性	值
配置键	`management-server-port`
数据类型	整数（0-65535）
默认值	`0`（随机分配）
典型值	`25585`（官方示例）、`8080`、`8443`

默认值为 0 时，服务端在启动时从操作系统获取可用临时端口，并将实际绑定端口写入日志。这一设计简化了多实例部署（避免端口冲突），但增加了客户端配置的动态性。静态端口配置（如 25585）适用于需要防火墙规则预设或客户端硬编码的场景。端口选择应避开 Minecraft 游戏端口（默认 25565）及常用服务端口，减少扫描攻击风险。

2.1.4 `management-server-secret`：40 位字母数字认证密钥#

属性	值
配置键	`management-server-secret`
数据类型	字符串（严格 40 字符）
默认值	空（启动时自动生成）
字符集	`[A-Za-z0-9]`

认证密钥是 MSMP 安全模型的核心。若配置为空，服务端在启动时自动生成 40 位随机字符串，并回写至 server.properties 文件。自动生成的密钥强度足够，但会导致配置文件变更，需在版本控制中注意忽略或同步。生产环境建议显式配置密钥，便于多节点一致性与密钥轮换管理。

密钥的 40 位长度与字符集限制经过安全考量：总密钥空间为 62^40 ≈ 2.7×10^71，远超暴力破解可行性；字母数字排除易混淆字符（如 O/0、I/l），降低人工抄录错误。客户端提交密钥时，服务端进行严格格式验证，非 40 位字母数字的密钥立即拒绝，返回 401 错误。

2.2 安全配置与 TLS 加密#

TLS 加密是 MSMP 生产环境的强制要求，协议设计将其作为默认安全策略。

2.2.1 `management-server-tls-enabled`：TLS 开关#

属性	值
配置键	`management-server-tls-enabled`
数据类型	布尔值
默认值	`true`

默认 true 体现了**默认安全（Secure by Default）**的设计原则。启用后，WebSocket 端点从 ws:// 升级为 wss://，所有通信内容经 TLS 1.2/1.3 加密，防止中间人攻击与窃听。

2.2.2 `management-server-tls-keystore`：PKCS12 证书库路径#

属性	值
配置键	`management-server-tls-keystore`
数据类型	字符串（文件路径）
格式要求	PKCS #12（`.p12` 或 `.pfx`）

Java 生态的标准 TLS 配置方式，指向 PKCS#12 格式的密钥库文件。密钥库包含服务器证书与私钥，可由 Let’s Encrypt 等 CA 签发，或自签名生成。

2.2.3 `management-server-tls-keystore-password`：密钥库密码（多来源优先级）#

密钥库访问密码的配置需考虑安全性与便利性的平衡。Java 支持三层密码来源优先级，从高到低：

优先级	来源	适用场景
1	环境变量 `MINECRAFT_MANAGEMENT_TLS_KEYSTORE_PASSWORD`	推荐，容器化与自动化部署
2	JVM 系统属性 `-Dmanagement.tls.keystore.password=`	多实例隔离
3	`server.properties` 配置项	开发与测试环境

生产环境强烈建议采用环境变量注入，避免密码泄露于配置文件或版本控制。

2.2.4 自签名证书生成与浏览器信任配置#

开发测试场景下，自签名证书是便捷选择。使用 OpenSSL 生成：

Terminal window

1
# 生成私钥与证书
2
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
3
  -sha256 -days 365 -nodes -subj "/CN=localhost" \
4
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
5

6
# 转换为 PKCS12
7
openssl pkcs12 -export -out minecraft.p12 -inkey key.pem -in cert.pem \
8
  -name minecraft -password pass:changeit

浏览器环境连接自签名 WSS 端点时，需先将证书导入系统信任库，或访问 https://localhost:<port> 手动确认例外（WebSocket 无法直接处理证书警告）。Node.js 等环境可通过 NODE_TLS_REJECT_UNAUTHORIZED=0 临时禁用验证（仅限开发使用）。

2.3 跨域与来源控制#

2.3.1 `management-server-allowed-origins`：浏览器 WebSocket 来源白名单#

属性	值
配置键	`management-server-allowed-origins`
数据类型	逗号分隔的字符串列表
默认值	空字符串（拒绝所有浏览器连接）
示例值	`https://admin.example.com,https://panel.example.org`

allowed-origins 是 MSMP 针对浏览器环境的安全强化机制。WebSocket 连接建立时，浏览器自动附加 Origin HTTP 头，服务端验证该值是否在白名单内。验证失败时，立即返回 HTTP 401 Unauthorized，终止连接。

这一机制有效防御了跨站 WebSocket 劫持（CSWSH）攻击：即使攻击者获取了有效密钥，若其网页来源不在白名单，浏览器将阻止 WebSocket 连接建立。配置时需注意：Origin 值包含协议与端口（如 https://admin.example.com:8443），白名单条目需精确匹配。

2.3.2 Origin 验证失败时的 401 响应行为#

来源验证失败与认证密钥失败的响应码均为 401，但日志中应区分具体原因以便排查。典型的错误响应结构：

1
HTTP/1.1 401 Unauthorized
2
Content-Type: text/plain
3

4
Origin not allowed: https://evil.com

或

1
HTTP/1.1 401 Unauthorized
2
Content-Type: text/plain
3

4
Invalid or missing authentication

生产环境建议启用详细日志记录，监控异常来源的访问尝试，作为安全态势感知的数据源。

2.4 启动验证与日志诊断#

2.4.1 成功启动标志：`Starting json RPC server on ...`#

服务端成功初始化 MSMP 时，日志输出关键信息：

1
[Server thread/INFO]: Starting json RPC server on localhost/127.0.0.1:25585
2
[Server thread/INFO]: Json-RPC Management connection listening on localhost/127.0.0.1:25585

首行确认绑定地址与端口，第二行确认服务器已进入监听状态。若端口配置为 0，此处显示实际分配的动态端口。两行日志的线程标识均为 Server thread，表明 MSMP 与主游戏服务器共享线程——MSMP 处理函数应避免阻塞操作，以免影响游戏 tick 。

2.4.2 绑定失败处理与端口冲突排查#

错误场景	日志特征	解决方案
端口被占用	`Address already in use: bind`	更换端口，或查找并终止占用进程
端口无效	端口范围错误提示	检查端口范围 1-65535
绑定地址无效	`Cannot assign requested address`	确认 IP 已配置在网络接口
权限不足	`Permission denied`	使用高位端口，或以 root 运行（不推荐）
TLS 密钥库错误	`Keystore was tampered with, or password was incorrect`	验证密码，检查文件完整性

端口冲突排查命令（Linux）：

Terminal window

1
sudo ss -tlnp | grep :8080  # 查看占用端口的进程
2
sudo lsof -i :8080          # 替代命令

2.4.3 防火墙与云服务器安全组配置#

场景	配置要求
本地开发	无需额外配置
同机管理工具	确保 `localhost` 可达
远程管理（内网）	防火墙放行指定端口，绑定内网 IP
远程管理（公网）	安全组放行 + TLS 强制 + 来源白名单

云服务器（AWS、Azure、阿里云等）需在安全组/网络 ACL 中显式放行 MSMP 端口。建议限制源 IP 范围至管理节点，而非 0.0.0.0/0，形成纵深防御。

3. 连接建立与认证机制#

3.1 WebSocket 连接端点#

3.1.1 非 TLS 端点：`ws://<host>:<port>`#

开发测试环境的默认连接方式。URL 格式示例：

1
ws://localhost:25585
2
ws://192.168.1.100:8080

非 TLS 连接的所有内容（包括认证密钥）以明文传输，仅适用于可信网络环境。生产环境公网暴露必须启用 TLS 。

3.1.2 TLS 端点：`wss://<host>:<port>`#

生产环境的标准连接方式。URL 格式示例：

1
wss://mc.example.com:8443
2
wss://10.0.0.5:25585

TLS 握手在 TCP 连接建立后立即开始，客户端验证服务端证书的可信性。证书验证失败（自签名、过期、主机名不匹配）会导致连接终止，错误信息因客户端而异。

3.2 认证方式（二选一）#

MSMP 提供两种互斥的认证机制，分别适用于不同客户端环境：

3.2.1 `Authorization` 请求头：`Bearer <40位密钥>`#

标准 HTTP 认证头格式，适用于非浏览器客户端（服务器端应用、命令行工具、桌面程序）：

1
// Node.js 示例
2
const ws = new WebSocket('ws://localhost:25585', {
3
  headers: {
4
    'Authorization': 'Bearer AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd'
5
  }
6
});

1
# Python websockets 示例
2
import websockets
3

4
async with websockets.connect(
5
    'ws://localhost:25585',
6
    extra_headers={'Authorization': 'Bearer ' + SECRET}
7
):
8
    ...

3.2.2 `Sec-WebSocket-Protocol` 请求头：`minecraft-v1,<40位密钥>`#

专门为浏览器 WebSocket API 设计的认证方式。浏览器 WebSocket 构造函数不支持自定义请求头，但原生支持 protocols 参数，该参数值会编码为 Sec-WebSocket-Protocol 头发送：

1
// 浏览器原生 WebSocket API
2
const ws = new WebSocket(
3
  'wss://mc.example.com:8443',
4
  ['minecraft-v1', 'AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd']
5
);

Sec-WebSocket-Protocol 头的标准格式为逗号分隔的子协议列表，MSMP 约定首项为固定字符串 minecraft-v1，第二项为认证密钥。服务端解析时验证这一结构，提取密钥进行认证。

3.2.3 浏览器环境强制使用 `Sec-WebSocket-Protocol` 的原因#

浏览器安全模型（CORS、CSP）严格限制 WebSocket 连接的可控性，禁止脚本设置任意 HTTP 头，以防止请求伪造攻击。Sec-WebSocket-Protocol 是少数可由 JavaScript 控制的头部之一，因其属于 WebSocket 标准协议的有机组成部分。MSMP 的这一设计妥协，确保了纯浏览器端管理面板（如基于 React/Vue 的 Web UI）的可行性，无需后端代理即可直接连接服务端。

3.3 认证失败处理#

3.3.1 HTTP 401 Unauthorized 响应#

认证失败时，WebSocket 握手阶段即返回 HTTP 401，连接未升级即终止。客户端表现为 WebSocket 构造抛出错误或连接事件触发失败。错误响应体包含具体原因，但浏览器端因安全限制通常无法读取，需服务端日志配合排查。

常见 401 原因：

完全缺失认证头
Authorization 头格式错误（非 Bearer <token>）
Sec-WebSocket-Protocol 头格式错误（缺少 minecraft-v1 或令牌）
令牌与 management-server-secret 不匹配
浏览器客户端的来源不在 allowed-origins 中

3.3.2 密钥格式验证：严格 40 位字母数字#

服务端对密钥进行两层验证：长度严格等于 40 字符，字符集限定于 [A-Za-z0-9]。任何偏离均立即 401 拒绝，不进入后续处理。这一严格验证防止了编码错误、截断密钥等常见配置问题的安全降级。

3.4 连接示例代码#

3.4.1 命令行工具：websocat 连接演示#

websocat 是功能强大的命令行 WebSocket 工具，适用于快速测试与脚本集成：

Terminal window

1
# 无认证尝试（预期失败）
2
$ websocat ws://localhost:40745
3
websocat: WebSocketError: Received unexpected status code (401 Unauthorized)
4

5
# 正确认证连接
6
$ websocat ws://localhost:40745 -H 'Authorization: Bearer n2pQcIG1OQ92jot2xG1M0aw0ZWnrh4F3Z3jw8qRP'
7
{"jsonrpc":"2.0","method":"server/status","id":0}
8
{"jsonrpc":"2.0","id":0,"result":{"started":true,"version":{"name":"25w37a","protocol":1073742092}}}
9

10
# TLS 连接（自签名证书）
11
$ websocat wss://localhost:40745 -H 'Authorization: Bearer ...' --insecure
12
# 或指定 CA 证书
13
$ websocat wss://localhost:40745 -H 'Authorization: Bearer ...' --ca-file cert.pem

3.4.2 Node.js 客户端：mc-server-management 库用法#

Aternos 团队维护的 mc-server-management 是目前最成熟的 Node.js 客户端库，提供高层 API 封装：

1
const { Server } = require('mc-server-management');
2

3
const server = new Server('ws://localhost:25585', {
4
  secret: 'AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd'
5
});
6

7
// 获取操作员列表包装器
8
const ops = server.operatorList();
9

10
// 异步获取所有操作员（自动缓存，通过通知更新）
11
const operators = await ops.get();
12
console.log(operators);
13

14
// 添加操作员（多种参数形式）
15
await ops.add('Notch');                          // 名称，默认等级
16
await ops.add('jeb_', 4, true);                  // 名称、等级4、绕过限制
17
await ops.add(Player.withId('uuid-here'), 2);    // UUID 对象
18

19
// 批量操作
20
await ops.add(['player1', 'player2'], 3, true);
21
await ops.remove(['player1', 'player2']);
22

23
// 设置完整列表（原子替换）
24
await ops.set([
25
  new Operator('Notch', 4, true),
26
  'jeb_',  // 使用默认参数
27
  Player.withId('uuid')
28
], 3, true);
29

30
// 清空列表
31
await ops.clear();

显示更多显示更少

该库的核心价值在于：自动处理连接管理、请求序列化、响应解析；基于通知实现本地缓存的增量更新；提供类型友好的批量操作接口。

3.4.3 浏览器原生 WebSocket API 连接#

1
<!DOCTYPE html>
2
<html>
3
<head>
4
  <title>MSMP 管理面板</title>
5
</head>
6
<body>
7
  <pre id="output"></pre>
8
  <script>
9
    const SECRET = 'AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd';
10
    const ws = new WebSocket(
11
      'ws://localhost:25585',
12
      ['minecraft-v1', SECRET]
13
    );
14

15
    ws.onopen = () => {
16
      log('Connected');
17
      // 获取玩家列表
18
      send({ jsonrpc: '2.0', method: 'minecraft:players', id: 1 });
19
    };
20

21
    ws.onmessage = (event) => {
22
      const msg = JSON.parse(event.data);
23
      log('Received: ' + JSON.stringify(msg, null, 2));
24
    };
25

26
    ws.onerror = (err) => log('Error: ' + err);
27
    ws.onclose = () => log('Disconnected');
28

29
    function send(msg) {
30
      ws.send(JSON.stringify(msg));
31
    }
32
    function log(text) {
33
      document.getElementById('output').textContent += text + '\n';
34
    }
35
  </script>
36
</body>
37
</html>

显示更多显示更少

浏览器示例展示了 Sec-WebSocket-Protocol 认证、消息收发、事件处理的基础模式。生产环境应添加重连逻辑、错误提示、UI 状态管理等增强功能。

4. JSON-RPC 2.0 通信规范#

4.1 请求格式#

4.1.1 必需字段：`jsonrpc`、`method`、`id`#

字段	类型	必需	说明
`jsonrpc`	字符串	是	固定值 `"2.0"`，标识协议版本
`method`	字符串	是	完整命名空间方法名
`id`	字符串/数字/null	是	请求标识，用于响应匹配
`params`	数组/对象	否	方法参数，MSMP 采用数组包裹

id 字段的选型建议：数字递增简单高效；字符串 UUID 避免冲突；null 仅用于通知（但通知应省略 id 而非设为 null）。客户端应确保同一连接内 id 的唯一性，通常采用单调递增计数器。

4.1.2 参数传递：`params` 数组包裹约定#

MSMP 的方法参数统一采用数组包裹，即使单参数也置于数组内：

1
// ✅ 正确：单参数数组包裹
2
{"method":"minecraft:allowlist/add","id":1,"params":[[{"name":"jeb_"}]]}
3

4
// ❌ 错误：直接传递对象
5
{"method":"minecraft:allowlist/add","id":1,"params":{"name":"jeb_"}}

这一设计源于 JSON-RPC 2.0 的 params 可为数组或对象的灵活性，MSMP 统一为数组以简化服务端解析逻辑。双层数组 [[...]] 在批量操作场景中出现：外层数组为参数列表（本方法仅一个参数），内层数组为批量元素数组。

4.1.3 命名空间方法完整格式：`minecraft:<group>/<action>`#

方法字符串的解析规则：以冒号分隔命名空间与路径，路径中以斜杠分隔功能组与操作。当前版本的标准功能组包括：

功能组	操作示例	说明
`players`	`players`	获取在线玩家列表
`allowlist`	`allowlist`, `allowlist/add`, `allowlist/remove`	白名单查询与修改
`operators`	`operators`, `operators/add`, `operators/remove`	管理员查询与修改
`server`	`server/save`, `server/stop`, `server/status`	服务器控制
`server-settings`	`server-settings`, `server-settings/set`	服务器设置
`game-rules`	`game-rules`, `game-rules/set`	游戏规则

4.2 响应格式#

4.2.1 成功响应：`result` 字段结构#

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "result": [
5
    {"id": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "jeb_"}
6
  ]
7
}

成功响应保留请求的 id，result 字段内容为方法特定的返回值。数组、对象、标量均可能，具体以 rpc.discover 模式或本文档方法章节为准。

4.2.2 错误响应：`error` 对象（code、message、data）#

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "error": {
5
    "code": -32601,
6
    "message": "Method not found",
7
    "data": "Method not found: minecraft:foo/bar"
8
  }
9
}

字段	类型	说明
`code`	整数	标准或应用定义的错误码
`message`	字符串	人类可读的错误描述
`data`	任意	附加诊断信息，可选

4.3 标准错误码对照#

4.3.1 `-32601` Method not found：方法不存在#

-32601 是 JSON-RPC 2.0 标准错误码，表示请求的方法未被服务端识别。MSMP 场景下的典型原因：

命名空间拼写错误（如 minecraft:player 而非 minecraft:players）
服务端版本不支持该方法（如旧版本无 server-settings 组）
方法尚未实现（自定义命名空间的预期行为）

客户端应将此错误视为致命或降级信号：致命意味着服务端版本不兼容，需升级或切换方法；降级意味着功能不可用，可提示用户或禁用相关 UI。

4.3.2 JSON-RPC 2.0 规范错误码全集#

错误码	名称	含义
`-32700`	Parse error	服务端接收到的 JSON 无法解析
`-32600`	Invalid Request	请求对象结构无效
`-32601`	Method not found	请求的方法不存在
`-32602`	Invalid params	方法参数无效（类型、数量、值）
`-32603`	Internal error	服务端内部错误
`-32000` 至 `-32099`	Server error	预留的应用定义错误

MSMP 可能扩展 -32000 范围的错误码表示特定领域错误（如玩家不存在、权限不足），客户端应预留处理未知错误码的弹性。

4.4 通知消息处理#

4.4.1 服务端主动推送特征：无 `id` 字段#

1
{
2
  "jsonrpc": "2.0",
3
  "method": "minecraft:notification/players/joined",
4
  "params": [{"id": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "jeb_"}]
5
}

通知消息的关键识别特征：id 字段完全缺失（非 null），method 字段以 notification: 开头。客户端解析时应优先检查 id 存在性，区分响应与通知的处理路径。

4.4.2 通知命名空间：`notification:<event>`#

事件类别	事件示例	触发时机
玩家生命周期	`minecraft:notification/players/joined`, `minecraft:notification/players/left`	玩家加入/离开服务器
游戏规则	`minecraft:notification/game-rules/updated`	任意游戏规则被修改

通知的 params 载荷结构与对应查询方法的返回元素一致，便于客户端复用解析逻辑。

5. 核心 API 方法组详解#

5.1 运行时 API 发现#

5.1.1 `rpc.discover`：动态获取服务端支持的方法与通知#

rpc.discover 是 MSMP 的元方法，无需认证即可调用（或作为首个验证连接的探针），返回当前服务端完整的 API 能力描述：

1
// 请求
2
{"jsonrpc":"2.0","method":"rpc.discover","id":1}
3

4
// 响应（结构示意）
5
{
6
  "jsonrpc": "2.0",
7
  "id": 1,
8
  "result": {
9
    "jsonrpc": "2.0",
10
    "info": {
11
      "title": "Minecraft Server JSON-RPC",
12
      "version": "2.0.0 (25w44a)"
13
    },
14
    "methods": [
15
      {
16
        "name": "minecraft:players",
17
        "params": [],
18
        "result": {"$ref": "#/components/schemas/PlayerArray"}
19
      }
20
      // ... 更多方法
21
    ],
22
    "notifications": [
23
      {
24
        "name": "notification:players/joined",
25
        "params": [{"$ref": "#/components/schemas/Player"}]
26
      }
27
      // ... 更多通知
28
    ],
29
    "components": {
30
      "schemas": {
31
        "Player": {
32
          "type": "object",
33
          "properties": {
34
            "id": {"type": "string", "format": "uuid"},
35
            "name": {"type": "string"}
36
          }
37
        }
38
        // ... 更多类型
39
      }
40
    }
41
  }
42
}

显示更多显示更少

5.1.2 响应结构：方法列表、参数模式、通知事件#

字段	内容
`info`	API 元数据（标题、版本）
`methods`	支持的方法数组，每项含 `name`、`params`（参数模式）、`result`（返回模式）
`notifications`	支持的通知数组，每项含 `name`、`params`（事件载荷模式）
`components/schemas`	可复用的类型定义，以 JSON Schema 格式描述

5.1.3 与静态 `json-rpc-api-schema.json` 的关系#

特性	`rpc.discover`	`json-rpc-api-schema.json`
获取时机	运行时	构建时（数据生成器）
内容时效	反映当前服务端实际能力	反映构建时的 API 版本
主要用途	动态客户端适配	静态代码生成
依赖条件	需运行服务端	需执行数据生成器

mc-rpc Rust 库的构建流程展示了静态模式的典型用法：build.rs 在编译期解析 json-rpc-api-schema.json，为每个方法生成异步函数，为每个类型生成 Rust 结构体，实现零开销的类型安全。

5.2 玩家管理（`minecraft:players`）#

5.2.1 `minecraft:players`：获取在线玩家列表#

1
// 请求
2
{"jsonrpc":"2.0","method":"minecraft:players","id":1}
3

4
// 响应
5
{
6
  "jsonrpc": "2.0",
7
  "id": 1,
8
  "result": [
9
    {"id": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "jeb_"},
10
    {"id": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "name": "Notch"}
11
  ]
12
}

返回当前在线玩家的完整列表。空服务器返回空数组 []。

5.2.2 玩家对象结构：UUID（`id`）、名称（`name`）#

字段	类型	格式	说明
`id`	字符串	UUID v4（带连字符）	玩家唯一标识，离线模式为离线 UUID
`name`	字符串	3-16 字符，合法 Minecraft 用户名	玩家显示名称

玩家对象是 MSMP 的核心引用类型，广泛嵌套于管理员、白名单等结构中。UUID 的解析与验证需注意：离线服务器（online-mode=false）使用基于用户名的离线 UUID 生成算法，与正版 UUID 不同，但格式一致。

5.2.3 相关通知：`minecraft:notification/players/joined`、`minecraft:notification/players/left`#

1
// 玩家加入通知
2
{
3
  "jsonrpc": "2.0",
4
  "method": "minecraft:notification/players/joined",
5
  "params": [{"id": "...", "name": "NewPlayer"}]
6
}
7

8
// 玩家离开通知
9
{
10
  "jsonrpc": "2.0",
11
  "method": "minecraft:notification/players/left",
12
  "params": [{"id": "...", "name": "LeavingPlayer"}]
13
}

通知载荷为单个玩家对象，而非数组。客户端可通过维护本地在线玩家集合，响应通知进行增量更新，避免频繁全量查询。

5.3 白名单管理（`minecraft:allowlist`）#

方法	功能	参数特点
`minecraft:allowlist`	查询白名单列表	无参数
`minecraft:allowlist/add`	添加白名单条目	支持批量，参数为玩家对象数组
`minecraft:allowlist/remove`	移除白名单条目	支持批量

5.3.2 `minecraft:allowlist/add`：添加白名单（支持 UUID/名称）#

1
// 请求：通过名称添加
2
{"method":"minecraft:allowlist/add","id":1,"params":[[{"name":"jeb_"}]]}
3

4
// 请求：通过 UUID 添加
5
{"method":"minecraft:allowlist/add","id":1,"params":[[{"id":"853c80ef-3c37-49fd-aa49-938b674adae6"}]]}
6

7
// 请求：批量添加
8
{"method":"minecraft:allowlist/add","id":1,"params":[[
9
  {"name":"player1"},
10
  {"id":"uuid-2"},
11
  {"name":"player3"}
12
]]}
13

14
// 响应：成功添加的玩家列表（含解析后的 UUID）
15
{
16
  "jsonrpc": "2.0",
17
  "id": 1,
18
  "result": [
19
    {"id": "...", "name": "jeb_"}
20
  ]
21
}

显示更多显示更少

params 的双层数组结构：外层数组为方法参数列表（本方法仅一个参数），内层数组为批量操作条目。每个条目为对象，含 name 或 id 字段。

5.3.4 批量操作与单条操作的参数差异#

操作类型	参数结构	示例
单条添加	`[[{"name":"player"}]]`	外层数组1元素，内层数组1元素
批量添加	`[[{"name":"p1"},{"id":"uuid"}]]`	外层数组1元素，内层数组N元素

批量操作的设计体现了性能优化考量：单次网络往返处理多个条目，减少 WebSocket 帧传输开销。

5.4 管理员管理（`minecraft:operators`）#

方法	功能
`minecraft:operators`	查询管理员列表
`minecraft:operators/add`	添加管理员，支持等级和绕过设置
`minecraft:operators/remove`	移除管理员

5.4.2 `minecraft:operators/add`：添加管理员（支持等级与绕过限制）#

添加管理员时，可以指定两个额外参数：

level：权限等级，1-4，控制可用命令范围
bypass：布尔值，是否绕过玩家数量限制

mc-server-management 库提供了优雅的操作员对象抽象：

1
// 使用默认等级和绕过设置
2
await ops.add('Aternos');
3

4
// 显式指定等级4，绕过限制
5
await ops.add('Aternos', 4, true);
6

7
// 通过 UUID 添加
8
await ops.add(Player.withId('player-uuid'), 2, false);

5.5 服务器控制（`minecraft:server`）#

方法	功能	注意事项
`minecraft:server/save`	保存世界数据	可能耗时较长，大服务器需考虑异步处理
`minecraft:server/stop`	优雅关闭服务器	触发保存并断开所有玩家
`minecraft:server/status`	查询服务器状态	包含启动状态和版本信息

状态查询响应示例：

1
{
2
  "jsonrpc": "2.0",
3
  "id": 0,
4
  "result": {
5
    "started": true,
6
    "version": {
7
      "name": "25w37a",
8
      "protocol": 1073742092
9
    }
10
  }
11
}

5.6 服务器设置（`minecraft:server-settings`）#

服务器设置管理允许查询和修改 server.properties 中的配置项。修改后的行为取决于具体设置——某些变更需要重启生效，某些则可以热加载。协议层面不区分这两种情况，客户端应通过文档或实验确定具体行为。

5.7 游戏规则（`minecraft:game-rules`）#

方法	功能
`minecraft:game-rules`	查询所有游戏规则
`minecraft:game-rules/set`	修改指定游戏规则

修改后会触发通知：

minecraft:notification/game-rules/updated：游戏规则发生变更

5.8 封禁玩家列表管理（`minecraft:bans`）#

封禁玩家列表相关方法共有5个，分别用于获取、设置、添加、移除及清空封禁玩家列表。

方法	功能	参数
`minecraft:bans`	获取当前封禁玩家列表	无
`minecraft:bans/set`	用新的封禁列表覆盖当前列表	封禁条目数组
`minecraft:bans/add`	将玩家添加到封禁列表中	封禁条目数组
`minecraft:bans/remove`	将玩家移出封禁列表	玩家对象数组
`minecraft:bans/clear`	清空当前封禁列表	无

封禁条目结构#

1
{
2
  "player": {"id": "uuid", "name": "playerName"},
3
  "reason": "封禁原因",
4
  "source": "操作者",
5
  "expires": "2026-01-01T00:00:00Z"
6
}

字段	类型	说明
`player`	对象	被封禁的玩家（PlayerDto）
`reason`	字符串	封禁原因
`source`	字符串	执行封禁的操作者
`expires`	字符串	封禁过期时间（ISO 8601格式），空字符串表示永久封禁

5.9 封禁 IP 列表管理（`minecraft:ip_bans`）#

封禁 IP 列表相关方法共有5个，分别用于获取、设置、添加、移除及清空封禁 IP 列表。

方法	功能	参数
`minecraft:ip_bans`	获取当前封禁 IP 列表	无
`minecraft:ip_bans/set`	用新的封禁列表覆盖当前列表	IP 封禁条目数组
`minecraft:ip_bans/add`	将 IP 添加到封禁列表中	IP 封禁条目数组
`minecraft:ip_bans/remove`	将 IP 移出封禁列表	IP 地址字符串数组
`minecraft:ip_bans/clear`	清空当前封禁 IP 列表	无

IP 封禁条目结构#

1
{
2
  "ip": "192.168.1.1",
3
  "reason": "封禁原因",
4
  "source": "操作者",
5
  "expires": "2026-01-01T00:00:00Z"
6
}

字段	类型	说明
`ip`	字符串	被封禁的 IP 地址
`reason`	字符串	封禁原因
`source`	字符串	执行封禁的操作者
`expires`	字符串	封禁过期时间（ISO 8601格式），空字符串表示永久封禁

5.10 玩家踢出（`minecraft:players/kick`）#

将指定玩家踢出服务器。

请求参数：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "minecraft:players/kick",
4
  "params": [{
5
    "player": [{"id": "uuid", "name": "playerName"}],
6
    "message": "踢出原因"
7
  }],
8
  "id": 1
9
}

字段	类型	必需	说明
`player`	数组	是	要踢出的玩家列表（PlayerDto 数组）
`message`	字符串	否	踢出时显示给玩家的消息

响应： 返回实际被踢出的玩家列表。

5.11 服务端消息发送（`minecraft:server/system_message`）#

向玩家发送服务端消息，可选择在聊天栏或动作栏显示。

请求参数：

1
{
2
  "jsonrpc": "2.0",
3
  "method": "minecraft:server/system_message",
4
  "params": [{
5
    "message": {
6
      "literal": "要发送的文本",
7
      "translatable": "chat.type.text",
8
      "translatableParams": ["参数1", "参数2"]
9
    },
10
    "overlay": false,
11
    "receivingPlayers": [{"id": "uuid", "name": "playerName"}]
12
  }],
13
  "id": 1
14
}

字段	类型	必需	说明
`message.literal`	字符串	条件	要发送的纯文本（与 translatable 二选一）
`message.translatable`	字符串	条件	本地化键名（如 `chat.type.text`）
`message.translatableParams`	数组	否	本地化文本的参数替换列表
`overlay`	布尔	是	是否在动作栏显示（`true`）而非聊天栏（`false`）
`receivingPlayers`	数组	否	指定接收消息的玩家列表，不指定则发送给所有玩家

响应： 布尔值，表示是否有玩家接收到了消息。

5.12 服务端设置管理（`minecraft:serversettings`）#

服务端设置相关方法共有 40 个，用于查询和修改 server.properties 中的配置项。

配置项	查询方法	设置方法
自动保存	`serversettings/autosave`	`serversettings/autosave/set`
世界难度	`serversettings/difficulty`	`serversettings/difficulty/set`
强制执行白名单	`serversettings/enforce_allowlist`	`serversettings/enforce_allowlist/set`
启用白名单	`serversettings/use_allowlist`	`serversettings/use_allowlist/set`
最大玩家数	`serversettings/max_players`	`serversettings/max_players/set`
无玩家暂停秒数	`serversettings/pause_when_empty_seconds`	`serversettings/pause_when_empty_seconds/set`
玩家空闲超时	`serversettings/player_idle_timeout`	`serversettings/player_idle_timeout/set`
允许飞行	`serversettings/allow_flight`	`serversettings/allow_flight/set`
服务器 MOTD	`serversettings/motd`	`serversettings/motd/set`
出生点保护半径	`serversettings/spawn_protection_radius`	`serversettings/spawn_protection_radius/set`
强制游戏模式	`serversettings/force_game_mode`	`serversettings/force_game_mode/set`
默认游戏模式	`serversettings/game_mode`	`serversettings/game_mode/set`
渲染距离	`serversettings/view_distance`	`serversettings/view_distance/set`
模拟距离	`serversettings/simulation_distance`	`serversettings/simulation_distance/set`
接受转移连接	`serversettings/accept_transfers`	`serversettings/accept_transfers/set`
心跳间隔	`serversettings/status_heartbeat_interval`	`serversettings/status_heartbeat_interval/set`
管理员权限等级	`serversettings/operator_user_permission_level`	`serversettings/operator_user_permission_level/set`
隐藏在线玩家	`serversettings/hide_online_players`	`serversettings/hide_online_players/set`
状态回复	`serversettings/status_replies`	`serversettings/status_replies/set`
实体广播范围	`serversettings/entity_broadcast_range`	`serversettings/entity_broadcast_range/set`

所有查询方法返回对应配置项的当前值，设置方法接受新值作为参数并返回设置后的值。

6. 通知事件系统#

6.1 通知机制设计#

6.1.1 服务端状态变更的实时推送#

MSMP 的通知机制是其相对于传统管理协议的核心优势。与轮询模式相比，通知驱动架构具有显著的效率和实时性优势：

对比维度	轮询模式	通知模式
延迟	轮询间隔决定，通常秒级	亚秒级，事件发生后立即推送
网络开销	与轮询频率成正比，大量无效请求	仅在有事件时产生流量
服务端负载	随客户端数量线性增长	与客户端数量无关，事件驱动
实现复杂度	客户端简单，服务端无特殊要求	需要持久连接和状态管理
可靠性	可能错过短暂状态变化	依赖连接稳定性，可设计重放机制

WebSocket 的全双工特性为通知机制提供了理想的传输基础。服务端可以在任意时刻向客户端推送消息，无需等待请求。

6.1.2 通知与轮询的效率对比#

以玩家在线状态监控为例：

RCON 轮询方案：每秒执行 list 命令，解析文本输出，对比前后差异。10 个监控客户端 = 服务端每秒处理 10 条命令。
MSMP 通知方案：玩家加入/离开时，服务端推送一次通知。10 个监控客户端 = 服务端推送 10 条消息，但仅在事件发生时。

对于 100 人在线、日均 500 次加入/离开的服务器，RCON 方案日处理 864,000 条命令，MSMP 方案仅处理 5,000 条通知——效率提升 170 倍。

6.2 标准通知事件类型#

6.2.1 服务端状态通知#

通知类型	触发条件	参数
`minecraft:notification/server/started`	服务端加载完毕，开始运行游戏主循环前	无
`minecraft:notification/server/stopping`	服务端接收到停止指令，开始执行停止前	无
`minecraft:notification/server/activity`	客户端成功建立连接并开始握手流程（30秒内最多一次）	无
`minecraft:notification/server/saving`	服务端保存所有区块前	无
`minecraft:notification/server/saved`	服务端保存所有区块后	无

6.2.2 玩家生命周期通知#

通知类型	触发条件	参数结构
`minecraft:notification/players/joined`	玩家加入服务器	玩家对象（`id`, `name`）
`minecraft:notification/players/left`	玩家离开服务器	玩家对象

1
// 玩家加入通知示例
2
{
3
  "jsonrpc": "2.0",
4
  "method": "minecraft:notification/players/joined",
5
  "params": [{"id": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "jeb_"}]
6
}

6.2.3 管理员列表变更通知#

通知类型	触发条件	参数结构
`minecraft:notification/operators/added`	管理员列表新增管理员	OperatorDto
`minecraft:notification/operators/removed`	管理员列表移除管理员	OperatorDto

6.2.4 白名单变更通知#

通知类型	触发条件	参数结构
`minecraft:notification/allowlist/added`	白名单新增玩家	玩家对象
`minecraft:notification/allowlist/removed`	白名单移除玩家	玩家对象

6.2.5 封禁列表变更通知#

通知类型	触发条件	参数结构
`minecraft:notification/ip_bans/added`	封禁 IP 列表新增 IP	IpBanDto
`minecraft:notification/ip_bans/removed`	封禁 IP 列表移除 IP	IP 地址字符串
`minecraft:notification/bans/added`	封禁玩家列表新增玩家	UserBanDto
`minecraft:notification/bans/removed`	封禁玩家列表移除玩家	玩家对象

6.2.6 游戏规则变更通知#

通知类型	触发条件	参数结构
`minecraft:notification/game-rules/updated`	游戏规则被修改	TypedRule（包含 `key`, `type`, `value`）

1
// 游戏规则更新通知示例
2
{
3
  "jsonrpc": "2.0",
4
  "method": "minecraft:notification/game-rules/updated",
5
  "params": [{"key": "doDaylightCycle", "type": "boolean", "value": false}]
6
}

6.2.7 服务端心跳通知#

通知类型	触发条件	参数结构
`minecraft:notification/server/status`	服务端发送心跳时（需配置 `status-heartbeat-interval`）	ServerState

6.3 自定义通知扩展（未来预留）#

MSMP 的命名空间预留机制为自定义扩展提供了规范路径。第三方服务器软件和模组可以使用非保留命名空间（即非 minecraft 和 notification）添加专属方法和通知。例如，Paper 服务器可以使用 paper: 命名空间，Fabric 模组可以使用模组 ID 作为命名空间前缀。

Not Enough Management（Fabric 模组）是社区扩展的实践案例，为原版 MSMP 添加了聊天消息通知等扩展功能：

扩展通知	来源	参数结构
`nem:chat_message`	Not Enough Management	`id`, `name`, `message`

扩展的最佳实践包括：使用反向域名风格的命名空间避免冲突；复用标准模式中的类型定义；在文档中明确说明扩展的依赖条件。

7. API 模式与代码生成#

7.1 静态模式文件获取#

7.1.1 数据生成器运行：`--reports` 参数#

数据生成器（Data Generator）是 Minecraft 内置的工具，用于导出游戏数据的各种结构化表示。运行数据生成器获取 API 模式：

Terminal window

1
java -jar server.jar --reports

7.1.2 `json-rpc-api-schema.json` 输出位置#

输出目录中将包含 reports/json-rpc-api-schema.json 文件，其内容与运行时 rpc.discover 响应一致。

7.2 模式文件结构解析#

键	内容
`methods`	支持的方法列表，每个包含名称、参数模式、返回模式
`notifications`	支持的通知列表，每个包含名称、参数模式
`components/schemas`	可复用的类型定义，JSON Schema 格式

7.3 客户端代码生成实践#

基于 JSON Schema 的代码生成可以显著提高开发效率和类型安全性。Rust 社区的 mc-server-management 实现展示了这一实践，利用 schemars 和 serde crate 从模式生成强类型客户端。

生成流程：

解析 json-rpc-api-schema.json
为每个方法生成请求/响应结构体
为每个通知生成事件处理类型
生成客户端 trait 或结构体，封装 WebSocket 连接管理

8. 插件开发最佳实践#

8.1 连接管理#

8.1.1 连接池与长连接维护#

MSMP 设计为长连接协议，客户端应保持单一连接而非频繁创建销毁。连接建立后，通过同一连接发送所有请求并接收通知。

8.1.2 断线重连与指数退避策略#

网络不稳定场景需要健壮的断线重连机制。推荐采用指数退避策略：

重试次数	等待间隔	累计等待
1	1s	1s
2	2s	3s
3	4s	7s
4	8s	15s
5+	60s（上限）	-

首次断线立即重试，后续间隔递增，避免对服务端造成重连风暴。

8.1.3 心跳检测与连接健康监控#

虽然 WebSocket 协议内置 Ping/Pong 帧，但应用层可以实现更语义化的心跳。定期发送 minecraft:server/status 请求，既可以检测连接健康，又可以同步服务端状态。

8.2 认证安全#

8.2.1 密钥安全存储：环境变量 vs 配置文件#

存储方式	安全性	便利性	适用场景
环境变量	⭐⭐⭐ 高	⭐⭐ 中	生产环境推荐
Docker Secrets/K8s Secrets	⭐⭐⭐ 高	⭐⭐ 中	容器化部署
配置文件（加密）	⭐⭐ 中	⭐⭐⭐ 高	小型部署
配置文件（明文）	⭐ 低	⭐⭐⭐ 高	仅限开发

8.2.2 密钥轮换与最小权限原则#

密钥轮换：MSMP 当前版本不支持动态密钥轮换，需要重启服务端生效。规划中的改进包括热重载配置和密钥版本控制。
最小权限：为不同用途的客户端分配不同密钥（未来版本支持），或通过网络隔离限制访问范围。

8.2.3 生产环境强制 TLS 配置#

检查项	要求
TLS 启用	`management-server-tls-enabled=true`
有效证书	公共 CA 签发或受信任的自签名
证书有效期	监控过期时间，自动续期
协议版本	TLS 1.2+，禁用 SSLv3/TLS 1.0/1.1

8.3 错误处理与容错#

8.3.1 JSON-RPC 错误码分类处理#

错误码范围	类型	处理策略
`-32700` ~ `-32600`	协议错误	记录日志，排查请求构造
`-32601`	方法不存在	检查版本兼容性，优雅降级
`-32602`	参数错误	验证输入，提示用户
`-32603`	内部错误	可能临时故障，可重试
`-32000` ~ `-32099`	服务端错误	监控告警，人工介入

8.3.2 网络超时与重试策略#

为每个请求设置合理的超时时间（建议 30s），避免无限等待。超时后应视为连接异常，触发重连。

8.3.3 服务端重启后的状态同步#

服务端重启后，客户端应：

重新执行 rpc.discover 获取当前能力
刷新所有缓存状态（玩家列表、白名单、游戏规则等）
重新注册通知处理器（若服务端状态丢失）

8.4 性能优化#

8.4.1 批量操作优先于单条调用#

操作	单条调用（10次）	批量调用（1次）
白名单添加	10 次往返	1 次往返
管理员设置	10 次往返	1 次往返

批量操作减少 90% 网络延迟。

8.4.2 通知订阅替代主动轮询#

数据类型	传统方案	MSMP 优化方案
玩家在线状态	每秒 `list` 命令	订阅 `minecraft:notification/players/joined` + `minecraft:notification/players/left`
游戏规则	定期全量查询	订阅 `minecraft:notification/game-rules/updated`
白名单	定期全量查询	本地缓存 + 增量更新

8.4.3 本地缓存与增量更新策略#

缓存策略：合理设置 TTL，游戏规则等不频繁变化数据可长期缓存
增量更新：收到通知后，更新本地缓存而非重新查询
失效处理：连接断开后，标记缓存失效，重连后全量刷新

8.5 调试与监控#

8.5.1 请求/响应日志记录#

环境	记录内容
开发	完整请求/响应 JSON
生产	方法名、响应时间、错误码、数据大小

8.5.2 性能指标采集#

指标	说明	告警阈值
连接建立时间	WebSocket 握手完成时间	> 5s
请求延迟（P50/P99）	请求到响应的时间	P99 > 1s
通知延迟	事件发生到推送到达的时间	> 100ms
错误率	失败请求占总请求比例	> 1%
重连频率	单位时间重连次数	> 10/分钟

9. 安全注意事项与风险防控#

9.1 网络暴露风险#

9.1.1 公网暴露的 TLS 强制要求#

MSMP 提供的服务器控制能力使其成为高价值攻击目标。公网暴露必须满足：

层级	措施
传输层	TLS 强制启用，使用有效证书
认证层	强认证密钥（40位随机字符）
应用层	来源验证（浏览器场景）
网络层	防火墙/安全组访问控制

9.1.2 反向代理部署模式#

推荐在生产环境使用反向代理（如 Nginx、Traefik）终止 TLS，提供额外的：

访问日志：集中审计
速率限制：防止暴力破解
WAF 保护：过滤恶意请求

9.2 认证密钥保护#

9.2.1 密钥泄露的潜在危害：完整服务器控制#

密钥泄露意味着攻击者获得：

修改白名单和管理员列表
执行服务器停止命令
更改游戏规则和服务器设置
潜在的权限提升路径

9.2.2 密钥生成与分发流程#

阶段	最佳实践
生成	加密安全随机数生成器（`crypto.randomBytes` 等）
分发	安全通道（SSH、密钥管理服务）
存储	环境变量或专用密钥管理系统
轮换	定期更换，制定应急响应流程

9.3 来源验证绕过风险#

allowed-origins 配置不当可能导致跨站 WebSocket 劫持（CSWSH）。严格遵循：

明确列出所有授权来源，不使用通配符
定期审计来源列表，移除不再使用的条目
监控 401 响应日志，检测潜在探测行为

9.4 权限最小化原则#

原则	实践
方法级最小权限	仅请求必要的 API 方法
读写分离	只读操作与写操作分离到不同插件
敏感操作确认	`server/stop` 等操作需要额外确认或审批

10. 生态工具与社区资源#

10.1 官方与半官方库#

库名称	语言	维护者	特点	状态
`mc-server-management`	Node.js	Aternos	高级抽象，自动缓存，通知同步	活跃维护
`mc-server-management`	Rust	社区	类型安全，异步运行时	活跃维护

10.2 扩展模组#

Not Enough Management（Fabric）

功能：为原版 MSMP 添加聊天消息通知等扩展
技术：自定义命名空间 nem:chat_message
参考价值：展示 MSMP 扩展机制的实践

10.3 第三方管理面板集成#

平台	集成状态	说明
Aternos	✅ 已集成	利用 MSMP 原生支持提供可靠管理体验
其他托管平台	评估中	预计 2025-2026 年逐步支持

10.4 相关协议对比#

10.4.1 MSMP vs RCON：功能、安全、实时性#

维度	MSMP	RCON
功能覆盖	完整 CRUD + 实时通知	仅命令执行
安全性	TLS + 40位密钥 + Origin 验证	明文密码
实时性	事件驱动，<10ms 延迟	轮询依赖，秒级延迟
迁移建议	新项目的首选方案	逐步迁移，利用通知替代轮询

10.4.2 MSMP vs Query：适用场景差异#

场景	推荐协议
服务器列表网站展示	Query（无认证，UDP 穿透性好）
实时管理面板	MSMP
第三方工具兼容	Query 与 MSMP 并存

10.4.3 MSMP vs 第三方 REST API 插件#

维度	MSMP	第三方 REST API
官方支持	✅ 原生集成	❌ 社区维护
版本同步	✅ 保证	⚠️ 不确定
功能完整性	✅ 完整	依赖插件
安全性	✅ 标准化	依赖实现
建议	新项目的首选	评估迁移成本

11. 历史版本更新记录#

版本	快照	发布日期	更新内容
1.21.9	25w35a	2025-08-26	首次加入服务端管理协议（MSMP）
-	25w37a	-	加入强制认证机制；支持 TLS 加密；支持批量请求格式
-	pre1	-	通知请求命名空间从 `notification:` 改为 `minecraft:notification/`
-	pre2	-	支持按名称指定参数
1.21.11	25w41a	-	协议版本号更新为 `1.1.0`；添加 `server/activity` 通知
-	25w42a	-	允许使用浏览器 WebSocket API 连入
-	25w44a	-	协议版本号更新为 `2.0.0`；修改游戏规则管理相关的请求和响应格式

12. 常见问题与故障排查#

12.1 连接问题#

12.1.1 401 Unauthorized：认证失败排查清单#

检查项	验证方法
密钥正确复制	无多余空格或换行
密钥长度 40 位	字符计数验证
认证头格式	`Bearer` 前缀或 `minecraft-v1,` 前缀
浏览器来源白名单	`allowed-origins` 包含页面 Origin
服务端日志	查看具体拒绝原因

12.1.2 连接被拒绝：端口、防火墙、绑定地址#

检查层级	命令/方法
服务端绑定状态	`ss -tlnp
操作系统防火墙	`firewall-cmd --list-ports`、`ufw status`
云安全组	控制台检查入站规则
绑定地址匹配	确认连接地址与绑定地址一致

12.2 调用问题#

12.2.1 Method not found：命名空间拼写、服务端版本#

排查清单：

检查命名空间拼写（minecraft 而非 minecrafts）
验证方法路径（allowlist/add 而非 allowlist.add）
确认服务端版本支持该方法
运行 rpc.discover 获取实际支持的方法列表

12.2.2 参数格式错误：数组包裹、对象字段#

常见错误	正确格式
`params: {"name": "player"}`	`params: [[{"name": "player"}]]`
批量操作单层数组	双层数组 `[[{...}, {...}]]`

12.3 性能问题#

12.3.1 高频率调用的限流与缓存#

优化策略	实施方法
通知替代轮询	订阅事件而非定时查询
批量操作合并	累积单条请求，定时批量发送
本地缓存	设置合理 TTL，增量更新
请求限流	客户端自我约束，避免服务端过载

13. 附录#

13.1 完整配置项速查表#

配置项	默认值	类型	说明
`management-server-enabled`	`false`	布尔	启用开关
`management-server-host`	`localhost`	字符串	绑定地址
`management-server-port`	`0`	整数	监听端口，0=随机
`management-server-secret`	自动生成	字符串(40)	认证密钥
`management-server-tls-enabled`	`true`	布尔	TLS开关
`management-server-tls-keystore`	无	字符串	PKCS12密钥库路径
`management-server-tls-keystore-password`	无	字符串	密钥库密码（多来源）
`management-server-allowed-origins`	无	逗号分隔字符串	浏览器来源白名单
`status-heartbeat-interval`	`0`	整数	心跳通知间隔（秒），0=禁用

13.2 HTTP/1.1 与 WebSocket 协议细节#

MSMP 要求 HTTP/1.1 作为 WebSocket 握手的传输层 。WebSocket 握手请求示例：

Authorization 认证方式：

1
GET / HTTP/1.1
2
Host: localhost:8080
3
Upgrade: websocket
4
Connection: Upgrade
5
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
6
Sec-WebSocket-Version: 13
7
Authorization: Bearer n2pQcIG1OQ92jot2xG1M0aw0ZWnrh4F3Z3jw8qRP

Sec-WebSocket-Protocol 认证方式（浏览器）：

1
GET / HTTP/1.1
2
Host: localhost:8080
3
Upgrade: websocket
4
Connection: Upgrade
5
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
6
Sec-WebSocket-Version: 13
7
Sec-WebSocket-Protocol: minecraft-v1,n2pQcIG1OQ92jot2xG1M0aw0ZWnrh4F3Z3jw8qRP
8
Origin: http://localhost:3000

13.3 JSON-RPC 2.0 规范参考链接#

资源	链接
JSON-RPC 2.0 规范	https://www.jsonrpc.org/specification
Minecraft Wiki - 服务端管理协议（中文）	https://zh.minecraft.wiki/w/服务端管理协议
Minecraft Wiki - MSMP（英文）	https://minecraft.wiki/w/Minecraft_Server_Management_Protocol

如何下载 B 站视频

Sun, 18 Jan 2026 00:00:00 GMT

B站上有许多优质的学习资源和优秀的二次创作视频。有时候为了方便离线观看或者存档，我们需要将视频下载到本地。

今天推荐三种不同维度的下载方法，涵盖了在线网站、浏览器插件以及专业客户端，总有一种适合你！

方法一：最便捷——SaveAny 在线下载（无需安装）#

如果你不想安装任何软件，只是偶尔下载一两个视频，那么使用在线解析网站是最简单的方案。

工具名称： SaveAny
访问地址： https://saveany.cn/
操作步骤：
1. 打开 B 站，复制你想要下载的视频页面 URL（链接）。
2. 访问 SaveAny 官网。
3. 将链接粘贴到搜索框中，点击解析按钮。
4. 解析完成后，点击链接下载即可。
优点： 跨平台（手机、电脑都能用），无需安装，即下即走。

方法二：最原生——Edge 浏览器下载助手（一键下载）#

如果你经常在电脑端使用浏览器看 B 站，安装一个插件可以实现“边看边下”，操作体验非常原生。

工具名称： Bilibili 哔哩哔哩下载助手
获取地址： Microsoft Edge 拓展商店
操作步骤：
1. 点击上方链接，将插件添加到你的 Edge 浏览器（Chrome 浏览器通常也可通用）。
2. 打开任意一个 B 站视频播放页面。
3. 你会发现在视频页面右下方或侧边出现了一个“下载视频”按钮。
4. 点击“合并下载”按钮，即可进行下载。
优点： 与网页集成度高，方便快捷。

方法三：最强大——Downkyi（哔哩下载姬）#

如果你需要批量下载整个收藏夹、整个 Up 主的视频，或者需要下载 4K 超高清画质，那么这款开源的桌面客户端是你的首选。

工具名称： Downkyi (哔哩下载姬)
获取地址： GitHub Releases
操作步骤：
1. 在 GitHub 发布页下载最新的压缩包并解压运行。
2. 登录你的 B 站账号（扫码登录后可下载已购内容或更高清晰度）。
3. 将视频链接、直播间链接或个人主页链接粘贴进输入框。
4. 设置好下载路径，勾选需要的文件，开启批量下载。
优点： 支持批量下载、支持断点续传、支持 4K/HDR/杜比视界（需大会员账号）、支持解析课程。

总结：我该选哪一个？#

偶尔下载、不想折腾： 选 方法一 (SaveAny)。
追求操作方便、随看随下： 选 方法二 (浏览器插件)。
专业需求、批量下载高清资源： 选 方法三 (Downkyi)。

⚠️ 温馨提示： 下载的视频仅供个人学习和离线观看，请务必尊重视频创作者的版权，严禁将下载内容用于商业用途或二次上传。

Vibe Coding 完全指南：从代码执行者到创意决策者的编程革命

Sat, 03 Jan 2026 00:00:00 GMT

引言：编程新纪元的到来#

你是否曾梦想过像产品经理一样“凭感觉”编程？不再纠结于语法细节，而是专注于产品愿景和用户体验？2025年初，OpenAI联合创始人Andrej Karpathy提出了一个革命性概念——“vibe coding”，它正在重新定义软件开发的本质。

Vibe coding是一种基于AI的软件开发方法，强调从传统的“How”（如何实现）思维转向“What”（实现什么）思维，让开发者能够像艺术家一样“凭感觉”创作代码，带来前所未有的沉浸式开发体验。

这场编程范式的转变不仅仅是技术层面的革新，更是一场思维革命。它意味着编程不再是少数技术精英的专属技能，而成为人人都能掌握的创意表达工具。通过将复杂的编码过程交给AI代理处理，开发者的角色从传统的代码编写者演变为系统架构师和创意决策者。在这个新时代，每个拥有创意的人都可以成为“vibe coder”，将脑海中的想法瞬间转化为可运行的应用程序。

本文将为你全面解析vibe coding的核心理念、主流工具和实践方法，帮助你从零开始掌握这种革命性的编程方式。无论你是编程初学者还是经验丰富的开发者，都能从中找到属于自己的vibe coding之路。

一、理解Vibe Coding：从“How”到“What”的思维跃迁#

1.1 什么是Vibe Coding？#

Vibe coding是一种AI驱动的软件开发方法，其核心是通过自然语言描述产品体验而非手动编写代码。这个概念由Andrej Karpathy在2025年2月的一条X（原Twitter）帖子中首次提出，他将其描述为“完全沉浸在氛围中，拥抱指数级增长，忘记代码的存在”。

从技术本质来看，vibe coding是一种探索式编程，以直观和提示驱动为特征。它包含三个核心要素：

环境沉浸感：通过视觉、听觉甚至触觉反馈打造专注的工作空间，让开发者完全沉浸在创作过程中
无摩擦交互：最小化从想法到实现之间的认知阻力，让创意能够流畅地转化为代码
即时正反馈：建立快速的奖励循环维持心流状态，每一次与AI的交互都能带来即时的成果展示

1.2 从“How”到“What”的思维转变#

传统编程模式下，开发者需要花费大量时间思考“How”——如何实现某个功能、如何编写正确的语法、如何处理边界条件等。这种思维模式要求开发者具备深厚的技术功底和丰富的编程经验。而vibe coding则将焦点从“How”转向“What”——关注产品的最终目标和用户体验，将实现细节交给AI处理。

这种思维转变带来了几个重要变化：

交互方式的革新：从编写精确语法转变为描述意图。开发者不再需要记忆复杂的API文档，只需用自然语言描述“我想要一个能够实时显示天气信息的仪表盘”，AI就能理解并生成相应的代码
开发流程的重构：从线性的设计-编码-测试流程转变为与AI对话的快速迭代循环。开发者可以先描述一个模糊的概念，然后通过与AI的持续对话逐步细化和完善，整个过程就像与一位经验丰富的编程伙伴协作
角色定位的升级：开发者的角色从代码工匠转变为解决方案架构师。你不再是代码的奴隶，而是创意的决策者和质量的把控者

1.3 心流状态：沉浸式开发的心理学基础#

Vibe coding的一个重要目标是帮助开发者进入心流状态。心流是由心理学家米哈里・契克森特米哈伊提出的概念，指个体完全投入某项活动时所体验到的一种充满吸引力的沉浸感。在心流状态下，人们会忘记时间的流逝，全神贯注于手头的任务，并且能够发挥出最高的创造力和效率。

研究表明，心流状态具有以下特征：

工作效率提升 500%
错误率降低 70%
工作满意度提高 300%

然而，传统IDE设计完全忽视了这些心理学原理，导致开发者平均每11分钟就被打断一次。Vibe coding通过减少认知负担、提供即时反馈、保持上下文连贯性等方式，帮助开发者更容易进入和维持心流状态。当你专注于产品愿景而非技术细节时，编程不再是枯燥的工作，而成为一种创造性的享受。

1.4 开发者角色的演变：从编码者到决策者#

生成式AI正在深刻改变软件开发的规则，推动开发者角色发生根本性转变。这种演变体现在以下几个方面：

从手动编码到编排验证：开发者需要从手动编写每一行代码转向编排、验证和架构设计。AI负责处理繁琐的代码生成工作，开发者则专注于更高层次的设计决策
架构责任的普及化：架构责任不再是高级工程师的专属特权。初级开发者也被要求考虑设计权衡，因为AI已经处理了较小的构建块。每个人都被拉入了架构思维模式
跨学科能力的融合：软件工程师、数据工程师和机器学习工程师之间的界限正在模糊。开发者需要具备更广泛的技能，包括提示工程、数据处理、分布式系统等知识
持续学习成为必需：随着AI工具的快速迭代，持续再培训已成为一种期望。团队需要定期更新知识，学习新的工具和技术

二、主流AI IDE和Coding Agent工具深度解析#

2.1 Claude Code：企业级AI编程助手#

Claude Code是由Anthropic开发的一款革命性AI编程工具，它将Claude Opus 4模型直接嵌入到开发者的终端中，具备深度代码库感知能力。作为企业级解决方案，Claude Code在处理大规模代码库和复杂业务逻辑方面表现卓越。

核心功能特性：

Claude Code最突出的特点是其全代码库理解能力。与大多数只能看到代码片段的AI助手不同，Claude Code可以理解整个项目的上下文，包括项目结构、依赖关系和设计模式。这种全局视角使得它能够做出更智能的代码建议和跨文件修改。

在代码生成方面，Claude Code展现出了卓越的能力。它能够洞察项目中已有的设计模式与编码规范，产出风格统一、无缝集成的“原生”代码。更重要的是，它能够精准执行跨越多文件的全局性修改，如批量更新API调用，这对于大型项目的重构工作尤为重要。

功能模块：

代码生成：根据自然语言描述生成完整的功能模块
代码重构：支持跨文件的大规模代码重构
代码理解：解析复杂代码库的结构和逻辑
智能问答：回答关于代码库的技术问题
多文件编辑：协调修改多个相关文件

定价策略：

Pro版：$17/月（年付），包含Claude Sonnet 4模型
Max版：$100/月，包含Claude Sonnet 4和Claude Opus 4双模型
企业版：$200/月，提供最高级别的API访问权限

2.2 Cursor：AI原生代码编辑器#

Cursor是一款专门为AI编程设计的现代化代码编辑器，被誉为“AI时代的最佳编程方式”。它将深度学习与自然语言处理技术深度融合，为开发者提供智能化的文本浏览与编辑服务。

技术架构优势：

Cursor的核心竞争力在于其全工程上下文感知技术。通过自动索引项目代码实现全局分析，它能够精准预测开发意图并提供多行代码建议。这种能力使得Cursor能够理解代码库的整体结构，而非仅仅关注当前文件。

在模型支持方面，Cursor集成了GPT-4与Claude 3.5双引擎，能够智能切换最优模型应对不同场景。这种多模型策略确保了在处理各种编程任务时都能获得最佳效果。例如，在处理需要复杂逻辑推理的任务时使用GPT-4，在处理安全敏感代码时使用Claude 3.5。

独特功能亮点：

Cursor的一个革命性功能是自然语言代码生成。开发者可以使用日常对话的方式生成完整功能模块，实现需求到代码的零障碍转化。这种交互方式彻底改变了传统的编程模式，让编程变得像聊天一样自然。

另一个值得关注的功能是Cursor的即时应用功能。当AI生成代码建议时，开发者可以通过点击代码块上方的播放按钮直接将建议应用到代码库中。这种无缝集成大大提高了开发效率，减少了手动复制粘贴的繁琐操作。

定价方案：

Hobby版：免费，包含2000次补全 + 50次请求/月
Pro版：$39/月，包含所有模型 + 1500次高级请求
Business版：$19/用户/月

2.3 CodeBuddy：腾讯云AI编程助手#

CodeBuddy是腾讯云推出的智能编程工具，基于腾讯混元和DeepSeek双轮模型驱动，为开发者提供从代码编写到项目部署的全链路AI辅助。作为国内领先的AI编程助手，CodeBuddy特别针对中文开发者进行了优化。

全链路AI辅助能力：

CodeBuddy的最大特色是其全链路AI辅助功能。它让开发者能够用自然语言描述需求，自动化完成从代码编写、测试、调试到部署的全链路开发任务。这种端到端的解决方案大大简化了开发流程，特别适合快速原型开发和MVP构建。

在智能体能力方面，CodeBuddy提供了Craft小程序编码智能体，专门为微信小程序开发设计。这个智能体能够理解小程序的特殊架构和开发规范，提供针对性的代码建议和功能生成。

跨平台支持：

CodeBuddy实现了插件、IDE、CLI三端全开发场景覆盖。无论你是在桌面IDE中进行深度开发，还是在命令行中快速编写脚本，CodeBuddy都能提供一致的AI辅助体验。

功能特性总结：

AI技术问答：实时解答编程问题
智能代码补全：基于上下文的精准补全
单元测试生成：自动生成测试用例
代码诊断：检测代码质量问题
智能评审：提供代码改进建议

定价信息：CodeBuddy IDE目前完全免费使用，无需付费即可体验所有AI编程功能。

2.4 Qoder：阿里巴巴智能编程平台#

Qoder是阿里巴巴推出的面向真实软件开发的Agentic编码平台，通过无缝集成增强上下文工程与智能代理，获得对代码库的全面理解。作为国内大厂的AI编程解决方案，Qoder在处理复杂企业级应用方面具有独特优势。

四大技术支柱：

Qoder的强大能力建立在四大技术支柱之上：

规则引擎：基于编程规则和最佳实践进行代码分析
持久记忆：记录项目历史和用户操作，形成个性化知识库
代码图谱：分析代码结构和依赖关系，构建项目知识图谱
智能索引：高效检索代码库内容，实现秒级定位

智能体架构：

Qoder提供了三种主要的交互模式：

代码建议模式：基于代码库感知的智能补全，不仅提供语法正确的代码，还确保架构一致性
智能问答模式：作为IDE内的AI专家，结合技术文档知识库和实时代码理解提供精准解答
智能体模式：支持将复杂的多步骤开发任务委托给AI，自动制定计划并执行

模型集成策略：

Qoder集成了多种全球顶尖AI模型，包括Claude、GPT、Gemini等，并会根据任务复杂度自动选择最合适的AI模型。这种智能的模型选择策略确保了在不同场景下都能获得最佳的代码生成效果。

2.5 OpenAI Codex：云端AI开发平台#

OpenAI Codex是OpenAI于2025年5月17日推出的基于云端的AI智能体，专注于自动化软件开发。作为GPT-5的一个专门版本，Codex在处理复杂编程任务方面展现出了卓越的能力。

多任务并行处理能力：

Codex的一个显著特点是其多任务并行处理能力。它可以同时处理多个开发任务，每个任务都在独立的云沙盒环境中运行。这种设计不仅提高了开发效率，还确保了任务之间的隔离性和安全性。

在功能方面，Codex具备代码编写、代码库问答、错误修复等核心能力。更重要的是，它能够读取和编辑文件，运行命令，包括测试套件和类型检查器。完成一个任务通常需要1到30分钟，具体取决于任务的复杂程度。

模型优化策略：

GPT-5-Codex是GPT-5的一个专门版本，经过特别优化用于AI软件工程任务。它在以下方面进行了针对性训练：

从头构建完整项目
添加功能和测试用例
调试复杂代码
执行大规模重构
进行代码审查

这种专业化的训练使得Codex在处理真实世界的工程任务时表现出色，能够理解复杂的业务逻辑和技术约束。

使用场景：

Codex可以在多个环境中运行，包括终端、IDE、云端、GitHub和手机。通过ChatGPT账户，开发者可以轻松地在本地环境和Codex的云沙盒之间移动工作，而不会丢失状态。这种无缝的环境切换能力大大提高了开发的灵活性。

三、Vibe Coding实践指南：从入门到精通#

3.1 思维准备：培养Vibe Coding意识#

学习vibe coding的第一步是进行思维模式的转变。你需要摒弃“我必须记住所有语法”的传统观念，转而拥抱“我如何清晰描述意图”的新思维。这种转变不仅仅是技术层面的，更是心态上的调整。

培养产品思维：

在vibe coding中，你需要像产品经理一样思考。不要只关注技术实现，而要思考：这个功能解决了什么问题？用户会如何使用它？什么样的交互体验是最好的？通过这种思维方式，你能够更清晰地向AI描述需求，得到更符合预期的代码。

接受渐进式开发：

Vibe coding是一个迭代的过程，不要期望一次提示就能得到完美的代码。你需要学会通过多次交互逐步完善你的应用。就像画家创作一样，先勾勒大致轮廓，然后逐步细化细节。

保持好奇心和实验精神：

Vibe coding是一个相对较新的领域，很多最佳实践还在探索中。保持好奇心，勇于尝试不同的提示方式和工具组合。记住，没有“错误”的尝试，每一次交互都是学习和优化的机会。

3.2 工具选择策略：找到适合你的AI编程伴侣#

选择合适的工具是成功进行vibe coding的关键。以下是针对不同需求的工具选择建议：

初学者友好型工具：

如果你是编程新手，以下工具特别适合入门：

Lovable：几乎完全通过对话和简单界面操作构建应用，无需任何编程知识
Glide + ChatGPT：经典组合，用Glide构建无代码界面，ChatGPT生成逻辑
Cursor：推荐从Cursor开始，它将代码编辑器和AI聊天完美融合，是目前AI IDE中使用量和评价最好的

专业开发者工具：

对于有经验的开发者，以下工具提供了更强大的功能：

Claude Code：适合处理大型代码库和复杂业务逻辑
Qoder：阿里巴巴的企业级解决方案，支持多模型集成
OpenAI Codex：云端平台，适合需要高性能计算的复杂任务

国内用户推荐：

考虑到网络和使用习惯，国内用户可以选择：

百度Comate：百度推出的AI编程助手
字节Trae：字节跳动的AI开发平台
CodeBuddy：腾讯云产品，完全免费且对中文支持友好

3.3 提示词工程：与AI高效沟通的艺术#

提示词工程是vibe coding的核心技能，它决定了AI生成代码的质量和准确性。以下是一些关键的提示词编写原则：

明确具体原则：

避免模糊的描述。例如，不要只说“创建一个按钮”，而应该详细描述：“使用React和Tailwind CSS创建一个蓝色的圆角按钮，文字为‘立即购买’，点击时触发支付流程”。越具体的描述，AI生成的代码越符合预期。

提供充分上下文：

当你想修改现有代码时，一定要提供相关的代码片段。如果涉及特定的技术栈或工具，也要明确告知。例如：“在这个Next.js项目中，修改header组件，使其在用户登录后显示用户名和退出按钮”。

分步迭代策略：

复杂的应用不可能通过一个提示词完成。采用分步策略：

先让AI生成基本框架
逐步添加功能
修改样式
修复bug和优化

这种迭代方式不仅提高了成功率，还让你更好地理解代码结构。

高级提示技巧：

随着经验的积累，可以学习更高级的技巧：

Few-Shot示例：给AI提供几个示例，让它模仿特定的风格或模式
思维链（Chain-of-Thought）：让AI先思考步骤再写代码，例如“首先检查用户输入是否合法，然后连接数据库，最后保存数据”
多模态输入：除了文字，还可以提供图片、设计稿等，AI在有视觉输入时表现会更好

避免常见错误：

不要在一个提示词中修复多个不相关的问题
保持每个任务的对话独立，避免上下文混乱
清晰命名状态和动作，使用动词开头的标签如“创建”、“分配”、“通知”

3.4 五维能力模型：构建完整的Vibe Coding技能体系#

根据Replit的官方指南，vibe coding需要掌握五大核心技能。这些技能相互关联，共同构成了完整的vibe coding能力体系。

1. 程序化思维（Procedural Thinking）

程序化思维要求开发者像产品经理和工程师的结合体一样思考。这不仅仅是基本的逻辑思维或计算思维，而是深入理解问题空间、期望结果和实现路径的能力。

具体实践步骤：

定义问题空间：明确应用要解决的核心问题，什么构成了成功的应用
规划MVP：确定第一个版本的绝对必要功能，从小处着手
任务分解：将高级目标分解为更小的可操作步骤或功能
预判边界情况：思考可能出错的情况，应用应该如何处理意外输入
考虑用户体验：什么构成了优秀的用户体验？需要存储什么数据？用户如何交互？

例如，在构建一个小费计算应用时，不要只要求“创建一个小费计算器”，而应该详细说明用户如何添加朋友、输入账单金额、处理税费/折扣以及分享结果。

2. 框架利用（Leveraging Frameworks）

你不需要从头开始构建所有内容，事实上也不应该这样做。无数的框架和库已经解决了常见问题（UI组件、动画、数据处理等）。

实践方法：

主动询问AI：“构建具有拖拽功能的用户界面有哪些好的选择？”或“处理用户认证的最佳方法是什么？”
检查兼容性：较新的框架可能不在AI的训练数据中，询问兼容性或直接在提示词中提供文档链接
提供具体信息：如果你找到了相关的库或代码片段，将其包含在提示词中，给AI具体的使用示例

需要注意的是，LLM有训练数据截止时间，非常新的框架可能需要你提供文档或示例作为上下文。

3. 检查点构建（Building in Checkpoints）

AI并不总是第一次就做对。一次性构建大型功能会增加出现复杂错误的风险。采用增量式工作方式。

具体实践：

定义小目标：提示AI一次构建一个小功能
测试每个步骤：AI完成任务后，运行代码，检查是否符合预期
使用检查点：许多AI IDE（如Replit）会自动创建检查点，捕获完整的开发状态
版本控制思维：将检查点视为保存整个开发环境的综合提交

当出现问题时，不要反复使用相同的请求，而应该回滚到之前的检查点，尝试不同的方法或提示词。

4. 系统化调试（Debugging Methodically）

错误是不可避免的。不要只是将错误消息粘贴回给AI，而应该采用系统化的调试方法。

调试流程：

理解错误：仔细阅读错误消息，确定错误发生的位置（控制台、浏览器、特定文件）
收集线索：查看错误周围的代码，检查控制台日志，使用AI助手解释不理解的代码部分
隔离问题：尝试可靠地重现错误，什么具体操作触发了它？
提供上下文线索：向AI寻求帮助时，提供：
- 确切的错误消息
- 相关的代码片段
- 你试图做什么
- 你已经尝试过什么
游戏化思维：将调试视为解决谜题，每个线索都让你更接近解决方案

5. 上下文掌控（Mastering Context）

你提供给AI的信息（上下文）极大地影响其响应质量。更多的上下文并不总是更好，相关的上下文才是关键。

上下文管理原则：

选择性提供：只包含与当前任务直接相关的信息，排除不需要的无关代码、文件或先前指令
使用多模态输入：提供代码片段、文件附件、错误消息、文档URL，甚至截图
清晰结构化提示词：先陈述目标，然后提供支持性上下文
新功能从头开始：开始全新功能时，考虑使用“新建聊天”，确保AI不会被先前的无关上下文混淆

想象一下向人类专家解释任务，如果你只需要帮助修复特定bug，你不会从讲述你的人生故事开始。给AI它需要的专注信息。

3.5 项目实践：从简单到复杂的进阶路径#

实践是掌握vibe coding的最佳方式。以下是为初学者设计的项目进阶路径：

初级项目（1-2天完成）：

个人作品集网站：向AI描述你的职业、技能、项目经历和期望的风格，让它为你生成一个静态网站
简单Web应用：
- 记事本应用：支持添加、删除、编辑笔记
- 天气查询应用：输入城市名显示实时天气
- 旅游规划应用：根据预算和时间推荐旅游路线
浏览器插件：
- 一键保存网页所有图片的插件
- 自动翻译网页选中文字的插件

中级项目（3-5天完成）：

AI驱动的应用：
- AI食谱推荐应用：用户输入食材，AI推荐菜谱
- 智能笔记系统：支持语音输入、自动分类、关键词搜索
- 个性化学习平台：根据用户进度推荐学习内容
实时协作工具：
- 多人在线文档编辑器
- 实时白板应用
- 团队任务管理系统

高级项目（1-2周完成）：

完整的电商平台：
- 商品展示和搜索
- 购物车和结算流程
- 用户账户系统
- 订单管理后台
数据分析仪表板：
- 实时数据可视化
- 交互式图表
- 数据导入和处理
- 自定义报告生成
机器学习应用：
- 图像分类器
- 情感分析工具
- 预测模型界面

3.6 最佳实践与经验总结#

经过大量实践，vibe coding社区总结出了以下最佳实践：

项目管理最佳实践：

模块化开发：将大型项目分解为小的功能模块，每个模块通过独立的提示词开发
版本控制：使用Git等版本控制系统跟踪代码变更，特别是AI生成的代码
文档编写：要求AI为生成的代码添加详细注释，这有助于后续维护

协作开发技巧：

当与团队协作时：

建立统一的提示词规范和风格指南
使用共享的AI上下文和项目知识库
定期进行代码审查，确保AI生成的代码符合团队标准

持续学习策略：

vibe coding是一个快速发展的领域，保持学习的方法：

关注AI模型的更新和新功能
学习新的提示词技巧和最佳实践
探索新的AI工具和集成方式
参与vibe coding社区，分享经验和学习心得

四、工具对比与选型建议#

4.1 功能特性对比分析#

为了帮助你更好地选择适合的工具，我们对主流AI编程工具进行了详细对比：

工具	核心优势	主要功能	适用场景	学习曲线
Claude Code	全代码库理解、跨文件编辑	代码生成、重构、智能问答	企业级大型项目	高
Cursor	双引擎支持、自然语言编程	代码补全、自然语言生成	全场景开发	中
CodeBuddy	免费、中文优化、全链路支持	代码生成、测试、部署	快速原型、MVP开发	低
Qoder	多模型集成、上下文感知	代码建议、智能问答、代理任务	复杂企业应用	高
OpenAI Codex	云端运行、多任务并行	全栈开发、复杂任务处理	专业开发	高

4.2 定价策略比较#

了解各工具的定价对于长期使用非常重要：

免费选项：

CodeBuddy：完全免费，无使用限制
Cursor Hobby：免费版包含2000次补全 + 50次请求/月
GitHub Copilot：学生和开源贡献者免费

低成本选项（$10-20/月）：

GitHub Copilot个人版：$10/月
Cursor Pro：$39/月（包含高级功能）
Claude Code Pro：$17/月（年付）

企业级选项（$50+/月）：

Claude Code Max：$100-200/月
Cursor Business：$19/用户/月
OpenAI Codex：按使用量计费

4.3 选型决策矩阵#

基于不同的使用场景，我们创建了一个选型决策矩阵：

个人开发者：

预算有限：CodeBuddy（免费）、Cursor Hobby（免费）
需要高级功能：Cursor Pro、Claude Code Pro
偏好云端：OpenAI Codex

团队开发：

企业级需求：Claude Code、Qoder
协作要求高：GitHub Copilot（集成GitHub）
成本敏感：CodeBuddy（免费）

初学者入门：

零编程基础：CodeBuddy、Lovable
想快速上手：Cursor、Replit
需要中文支持：CodeBuddy、百度Comate

结语：开启你的Vibe Coding之旅#

核心要点回顾#

通过本文的学习，我们了解到vibe coding不仅仅是一种新的编程方式，更是一场思维革命。它将编程从技术细节中解放出来，让每个人都能成为创意的表达者。

关键概念总结：

Vibe coding是基于AI的软件开发方法，强调从“How”到“What”的思维转变
它帮助开发者进入心流状态，工作效率可提升500%
开发者角色从代码编写者演变为系统架构师和创意决策者

主流工具特点：

Claude Code：适合企业级大型项目，具备全代码库理解能力
Cursor：双引擎支持，自然语言编程体验优秀
CodeBuddy：完全免费，对中文用户友好，适合快速原型开发
Qoder：阿里巴巴产品，多模型集成，适合复杂应用
OpenAI Codex：云端运行，支持多任务并行处理

核心技能要求：

程序化思维：像产品经理和工程师一样思考
提示词工程：清晰准确地描述需求
系统化调试：掌握与AI协作解决问题的方法
上下文管理：提供相关且必要的信息

未来展望：Vibe Coding的发展趋势#

Vibe coding正处于快速发展期，未来的发展趋势值得期待：

技术演进方向：

多模态交互：结合语音、手势、视觉等多种输入方式
更智能的AI代理：具备更强的理解能力和自主决策能力
实时协作：支持多人同时与AI协作开发
跨平台集成：无缝整合各种开发工具和服务

对行业的影响：

降低编程门槛，让更多人参与软件开发
提高开发效率，缩短产品上市时间
改变软件架构设计方式，更多依赖AI生成的代码
创造新的职业机会，如AI提示词工程师、AI系统架构师

给初学者的行动建议#

立即开始的三个步骤：

选择工具并注册：根据你的需求选择一个工具（推荐从CodeBuddy或Cursor开始），完成注册和基础配置。记住，最好的工具是你实际会使用的工具。
从简单项目开始：不要一开始就尝试构建复杂的应用。从个人作品集、简单的Web应用或浏览器插件开始。每天花30分钟到1小时练习，坚持一周你就会看到明显进步。
加入学习社区：
- GitHub上关注vibe coding相关的项目和讨论
- 加入相关的Reddit社区（如r/learnprogramming）
- 参加线下或线上的vibe coding聚会
- 关注技术博客和YouTube频道，学习他人的经验

持续成长的建议：

每天练习：哪怕只有10分钟，保持对AI工具的熟悉感
记录经验：建立一个笔记本，记录成功的提示词和遇到的问题
分享学习成果：将你的项目和经验分享到社区，这不仅能帮助他人，也能加深自己的理解
保持耐心：Vibe coding是一个新领域，不要期望一夜之间成为专家。享受学习的过程，每一次尝试都是进步的机会

最后的思考#

Vibe coding代表着编程的未来——一个更加人性化、创意化和民主化的未来。在这个未来里，技术不再是障碍，而是实现创意的工具。无论你是学生、产品经理、设计师还是其他行业的从业者，都可以通过vibe coding将你的想法变成现实。

记住Andrej Karpathy的话：“完全沉浸在氛围中，拥抱指数级增长，忘记代码的存在”。这不是让你真的忘记代码，而是让你超越代码的细节，专注于创造的快乐。当你能够像描述梦想一样描述你的应用时，你就真正掌握了vibe coding的精髓。

现在，是时候放下对编程的恐惧，拥抱这个充满可能性的新时代了。打开你的AI编程工具，输入第一个提示词，开始你的vibe coding之旅吧！相信我，当你看到AI将你的想法转化为可运行的代码时，那种成就感将让你爱上这种全新的编程方式。

愿每一个创意都能通过vibe coding变成现实，愿每一个人都能成为自己梦想应用的创造者。编程的未来，由你定义！

使用PyInstaller打包Python程序为EXE文件

Fri, 20 Jun 2025 00:00:00 GMT

使用PyInstaller打包Python程序指南#

准备工作#

准备Python脚本文件（如main.py）
可选：准备程序图标文件（.ico格式）

打包步骤#

1. 打开命令窗口#

在资源管理器中导航到脚本所在目录，在地址栏输入cmd回车：

打开命令窗口

2.安装PyInstaller#

基础安装命令#

Terminal window

1
pip install pyinstaller

使用国内镜像源加速安装#

Terminal window

1
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pyinstaller

安装pyinstaller

3. 基本打包命令#

Terminal window

1
pyinstaller -F 你的脚本.py

基本打包

4. 带图标的打包命令#

Terminal window

1
pyinstaller -F -i 图标.ico 你的脚本.py

5. 高级选项#

参数	说明
`-w`	隐藏控制台窗口（GUI程序适用）
`--clean`	清理临时文件
`--onefile`	单文件打包（与`-F`相同）
`--noconsole`	不显示控制台窗口

查找生成文件#

打包完成后，在dist文件夹中可以找到生成的EXE文件：

代码示例#

1
import random
2

3
while True:
4
    print("欢迎来到猜数字游戏！")
5
    ans = random.randint(1, 100)
6
    #print(ans)
7
    times = 0
8
    max_times = 3
9

10
    while True:
11
        try:
12
            num = int(input("请输入一个1-100之间的正整数："))
13
        except ValueError:
14
            print("输入不合法！请输入一个整数！！！")
15
            continue
16

17
        if num < 1 or num > 100:
18
            print("你输入的数不在1-100之间！请重新输入！！！")
19
            continue
20

21
        times = times + 1
22

23
        if num > ans:
24
            print(f'第{times}次尝试：大了！')
25
        elif num < ans:
26
            print(f'第{times}次尝试：小了！')
27
        else:
28
            print(f'恭喜你，猜对了！你总共猜了{times}次')
29
            break
30

31
        if times == max_times:
32
            print(f'你已用完{max_times}次机会，游戏失败！这个数是：{ans}')
33
            break
34

35
    play_again = input("再玩一次吗？(输入y继续，其他任意键退出)：")
36
    if play_again.lower() != 'y':
37
        break

显示更多显示更少

exe示例文件下载#

无图标提取码: 3936
有图标提取码: i8vn

Note

可以使用图标转换工具将图片转为ICO格

脚本引擎 V2.0.0 概述

Wed, 29 Jan 2025 00:00:00 GMT

Note

原文：微软文档

日期：2025 年 1 月 29 日

翻译：rice_awa

源项目许可证

脚本引擎 V2.0.0 概述#

我们还提供了脚本API v2.0.0-beta概述的视频版本：

[!VIDEO https://www.youtube.com/embed/owfBDnOHI_o]

脚本API v2.0.0的新特性#

通常，当你听说喜爱软件的”第二版”时，总会充满期待。一个全新的…事物！一切都不同了，而且应该会更好！但关于脚本API v2.0.0首先要明白的是：它与Minecraft脚本v1.x.0版本的区别并没有想象中那么大。请不要误解：我们对脚本API v2.0.0的基础架构改进感到兴奋，但也希望您能认同它与之前版本差异并不算太大。

您看，脚本版本遵循语义化版本规则。任何破坏向后兼容性的变更都需要升级主版本号。这就是脚本API v2.0.0的意义所在：它修复了API结构中的一些问题，这些改进虽然有益，但如果将针对v1.0.0编写的代码升级到v2.0.0，可能会导致原有代码失效。我们会周期性地推出修复问题和改进功能的新脚本版本，但这些版本可能不完全兼容当前的API”契约”。因此，您应该预期Minecraft脚本API命名空间会有主版本升级；例如，脚本API 3.0.0版本可能在不远的将来就会到来。

只要您在manifest.json中指定使用Minecraft API的1.x.0版本，所有针对v1.0.0编写的现有脚本和体验内容都能继续正常工作。未来多年Minecraft都会继续支持这些版本。它们会在最大限度保持1.0.0语义兼容的环境中运行，您的脚本无需任何修改。也就是说，当2.0.0版本结束测试进入稳定阶段后，建议将新项目或进行中的项目迁移到更现代的脚本2.0.0环境，特别是那些仅面向2.0.0的新API发布时。

Important

脚本V2.0.0 API目前处于实验预览阶段，需要使用”Beta API”实验性功能。在稳定并正式发布前，这些API可能还会有所调整。

以下是脚本API 2.0的主要变化：

脚本环境更早的执行与加载#

当前的脚本1.0.0环境是在Minecraft加载完部分其他基础架构（如实体定义等）后才加载到世界中的。即便如此，在脚本1.0.0中，脚本逻辑的首次执行通常发生在第一个区块加载之前，因此环境仍处于半加载状态。通常需要等待后续周期——比如经过若干游戏刻后，或玩家加入时，或方块可用时——才执行附加包的”真正”初始化逻辑。

世界加载流程

在脚本v2.0.0中，脚本初始化的首次执行时间被提前到世界启动和加载的更早阶段。此时大多数API——甚至是像获取世界游戏模式这样的简单属性查询——都尚未就绪。此举是为了让脚本能在其他内容加载前配置服务器和世界的初始化部分。例如，即将推出的自定义组件v2功能现在会在加载方块JSON文件前通过脚本注册，从而在方块JSON文件出错时提供更好的错误信息。

为了让行为更可预测，我们为API添加了更多保护措施，防止在未加载状态下被调用（早期执行特权）。同时还更新了一系列事件（新增worldLoad事件和startup事件），以便您可以在完全加载后运行代码。

Promise解析机制的变更#

在脚本V2.0.0中，promise现在可以在游戏刻结束时与after事件和系统任务一起解析。在之前的脚本版本中，promise每个游戏刻只解析一次。这项变更将使promise在其等待的操作完成后更频繁、更即时地得到解析。

脚本V2.0.0的刷新顺序#

在V1脚本中，系统会在每个游戏刻结束时持续刷新after事件和系统任务，直到脚本看门狗超时或没有待处理任务。在V2版本中，promise解析改为持续刷新机制。promise将单独解析，同时也会在每个after事件类型和每个系统任务执行后解析。

脚本刻处理流程

总的来说，V1和V2脚本的新刷新顺序如下：

在游戏刻结束时解析V1 promise一次
持续刷新直到没有待处理任务
- 解析V2 promise
- 运行系统任务（V1和V2）
  - 每个任务执行后解析V2 promise
- 运行after事件（V1和V2）
  - 每个事件类型执行后解析V2 promise

示例#

1
new Promise<void>(resolve => {
2
    resolve();
3
}).then(_ => {
4
    console.error('Promise已解析');
5
});

在V1中，上述示例会在下一游戏刻打印日志。而在V2中，promise会在同一游戏刻内刷新，这意味着会在当前游戏刻打印日志。

1
await system.waitTicks(1);
2
await system.waitTicks(0); // 在v1中不可行

V2还新增了用waitTicks函数等待0刻的能力。之前在V1中，由于promise要到下一游戏刻才会解析，所以无法等待0刻。现在随着promise的即时刷新，可以等待0刻并在当前刻执行。

其他API层面的变更#

除了脚本加载和promise解析行为的基础架构变更外，还有几个API发生了变化。查看变化的最佳方式是使用2.0.0-beta的TypeScript定义（例如运行npm i @minecraft/server@2.0.0-beta），然后在您选择的代码编辑器中查看变化。

实体：
- applyKnockback方法现在接受表示击退水平力的VectorXZ参数（包含强度/大小）和垂直强度参数。要从V1转换，您应该规范化之前的方向向量并乘以旧的水平强度值。垂直强度与之前相同。
维度：
- 移除了runCommandAsync，因为大多数命令实际上不是异步运行的。如需异步运行函数，请考虑通过System.runJob使用Jobs系统。
实体组件：
- getComponents、getComponent和hasComponent现在会在实体无效时抛出异常
- EntityComponent.getEntity方法在底层实体无效时会抛出异常（之前是返回undefined）
- EntityInventoryComponent.container属性在底层实体无效时会抛出异常（之前是返回undefined）
多个类上的isValid方法已改为只读属性
效果类型：
- getName方法现在总是返回带minecraft:命名空间前缀的名称
效果：
- typeId属性现在总是返回带minecraft:命名空间前缀的名称
minecraft:air物品已被移除（但它仍是有效的方块）

自定义组件V2#

“自定义组件V2”是一项新实验功能，需要同时启用”Beta API”实验功能才能使用。启用实验后：

minecraft:custom_components已被弃用，改用扁平化自定义组件
自定义组件现在支持参数

扁平化#

在之前版本中，自定义组件必须列在minecraft:custom_components组件内。现在不再需要这样做，minecraft:custom_components组件已被弃用。您可以像其他Minecraft组件一样编写自定义组件。例如：

1
{
2
    "components": {
3
        "minecraft:loot": "...",
4
        "minecraft:collision_box": {
5
            "enabled": true
6
        },
7
        "my_custom_component:name": {},
8
        "my_custom_component:another_component": {}
9
    }
10
}

参数#

除了在JSON中扁平化自定义组件外，您现在还可以为组件提供参数。自定义组件的脚本绑定已升级，支持第二个参数CustomComponentParameters，用于访问组件的JSON参数列表。以下示例展示了如何在脚本中使用自定义组件参数：

1
{
2
    "components": {
3
        "some_component:name": {
4
            "first": "hello",
5
            "second": 4,
6
            "third": [
7
                "test",
8
                "example"
9
            ]
10
        }
11
    }
12
}

1
type SomeComponentParams = {
2
    first?: string;
3
    second?: number;
4
    third?: string[];
5
};
6

7
system.beforeEvents.startup.subscribe(init => {
8
    init.blockComponentRegistry.registerCustomComponent('some_component:name', {
9
        onStepOn: (e : BlockComponentStepOnEvent, p : CustomComponentParameters) : {
10
            let params = p.params as SomeComponentParams;
11
            ...
12
        }
13
    });
14
});

升级到脚本V2.0.0#

启动事件#

world.afterEvents.worldInitialize的用法应改为world.afterEvents.worldLoad，无需额外修改。该事件在脚本v2.0.0中进行了重命名。

world.beforeEvents.worldInitialize的用法应改为system.beforeEvents.startup。worldInitialize前置事件已被移除，取而代之的是新的startup事件。但新的startup事件同样在早期执行阶段运行。这意味着之前在worldInitialize中允许的部分代码在startup中将不再有效。诸如获取玩家、访问游戏中的角色和方块等操作，应移至world.afterEvents.worldLoad事件中。

`world`对象#

早期执行带来的最大变化是，如果在脚本环境的早期执行阶段调用world对象的大多数方法会导致错误。订阅事件仍然有效，因为这不会访问世界状态，但任何与世界状态、实体、方块、玩家交互的操作都会受到限制，直到第一个游戏刻开始。

脚本启动流程#

为了向后兼容，脚本V1.x.x的启动时间和能力没有修改。脚本v1.x.x不使用早期执行，会保持当前的时间点运行。服务器加载脚本的一般流程如下：

加载并运行V2脚本（早期执行）
V2脚本在早期执行阶段接收system.beforeEvents.startup事件
等待世界完成加载和游戏启动…
加载并运行V1脚本
V1脚本接收world.beforeEvents.worldInitialize事件
第一个游戏刻开始…
在游戏刻结束时，所有脚本接收world.afterEvents.worldLoad事件（V1中称为worldInitialize）

早期执行阶段可用的API有哪些？#

以下是脚本v2.0.0-beta在早期执行模式下最初可用的API：

world.beforeEvents.*.subscribe
world.beforeEvents.*.unsubscribe
world.afterEvents.*.subscribe
world.afterEvents.*.unsubscribe
system.afterEvents.*.subscribe
system.afterEvents.*.unsubscribe
system.beforeEvents.*.subscribe
system.beforeEvents.*.unsubscribe
system.clearJob
system.clearRun
system.run
system.runInterval
system.runJob
system.runTimeout
system.waitTicks
BlockComponentRegistry.registerCustomComponent
ItemComponentRegistry.registerCustomComponent

如何处理脚本根上下文中不支持早期执行的代码？#

如果您有代码在脚本文件的根上下文中使用API，需要将其延迟到world.afterEvents.worldLoad事件期间或之后执行。有多种代码组织方式可以实现这一点。使用类或函数可以帮助组织各个系统的启动逻辑，这些逻辑可以在事件回调中调用。可以创建惰性getter来调用API并缓存结果，但只在getter被调用后执行。在许多情况下，您只需将”根上下文”脚本包装在world.afterEvents.worldLoad调用中即可。

总结#

就是这样！请继续关注2.0.0-beta API的更多更新；在接下来的几周里，我们还会在一些地方更改某些方法和属性的签名。一如既往，我们非常重视您在2.0.0测试期间的反馈和错误报告。您可以在bugs.mojang.com提交问题。

MCBE Agent Command

Wed, 28 Aug 2024 00:00:00 GMT

MCBE Agent Command#

介绍MCBE Agent 命令的语法、参数、用法。

语法#

agent command: AgentDirectionCommand direction: AgentDirection

agent command: AgentItemCommand slotNum: int

agent command: AgentCommand

agent collect item: Item

agent collect all

agent drop slotNum: int quantity: int direction: AgentDirection

agent place slotNum: int direction: AgentDirection

agent setitem slotNum: int item: Item count: int aux: int

agent tp [destination: x y z] [y-rot: float]

agent tp destination: x y z facing lookAtPosition: x y z

agent transfer slotNum: int quantity: int dstSlotNum: int

agent turn direction: AgentTurnDirection

参数#

command: AgentDirectionCommand#
- 包括 move | destroy | detect | attack | detectredstone | dropall | inspect | inspectdata | interact | till
- 用于命令：agent <command: AgentDirectionCommand> <direction: AgentDirection>
command: AgentItemCommand#
- 包括 getitemcount | getitemspace | getitemdetail
- 用于命令：agent <command: AgentItemCommand> <slotNum: int>
command: AgentCommand#
- 包括 create | getposition
- 用于命令：agent <command: AgentCommand>
direction: AgentDirection#
- 包括 up | down | forward | back | left | right
- 用于命令：agent <command: AgentDirectionCommand> <direction: AgentDirection>，agent drop <slotNum: int> <quantity: int> <direction: AgentDirection>，agent place <slotNum: int> <direction: AgentDirection>
direction: AgentTurnDirection#
- 包括 left | right
- 用于命令：agent turn <direction: AgentTurnDirection>
slotNum: int#
- 指定要改变的智能体物品栏槽位。有效值为0至26的整数。
- 用于命令：agent <command: AgentItemCommand> <slotNum: int>，agent drop <slotNum: int> <quantity: int> <direction: AgentDirection>，agent place <slotNum: int> <direction: AgentDirection>，agent setitem <slotNum: int> <item: Item> <count: int> <aux: int>，agent transfer <slotNum: int> <quantity: int> <dstSlotNum: int>
item: Item#
- 指定要给予或收集到物品栏槽位内的物品。必须为物品ID，或具有物品形态的方块的ID。
- 用于命令：agent collect <item: Item>，agent setitem <slotNum: int> <item: Item> <count: int> <aux: int>
quantity: int 和 count: int#
- 指定被丢出、给予或移动的物品数量。
- 用于命令：agent drop <slotNum: int> <quantity: int> <direction: AgentDirection>，agent setitem <slotNum: int> <item: Item> <count: int> <aux: int>，agent transfer <slotNum: int> <quantity: int> <dstSlotNum: int>
aux: int#
- 指定参与命令的物品的数据值。
- 用于命令：agent setitem <slotNum: int> <item: Item> <count: int> <aux: int>
destination: x y z#
- 指定要被传送到的坐标。必须为三维坐标，元素为单精度浮点数。允许相对坐标（~ ~ ~）或局部坐标（^ ^ ^）。
- 用于命令：agent tp [destination: x y z] [y-rot: float]，agent tp <destination: x y z> facing <lookAtPosition: x y z>
y-rot: float#
- 指定传送后智能体的水平旋转角度。
- 用于命令：agent tp [destination: x y z] [y-rot: float]
lookAtPosition: x y z#
- 指定传送后智能体朝向的位置。必须为三维坐标，元素为单精度浮点数。允许相对坐标（~ ~ ~）或局部坐标（^ ^ ^）。
- 用于命令：agent tp <destination: x y z> facing <lookAtPosition: x y z>
dstSlotNum: int#
- 指定目标物品栏槽位。
- 用于命令：agent transfer <slotNum: int> <quantity: int> <dstSlotNum: int>

MCBE WebSockets 完整函数描述文档

Fri, 16 Aug 2024 00:00:00 GMT

Minecraft基岩版WebSocket服务器 - 完整函数文档#

本文档详细介绍了Minecraft基岩版WebSocket服务器项目中的所有函数。

总述#

这个项目实现了一个Minecraft基岩版（MCBE）的WebSocket服务器，旨在通过WebSocket连接与游戏客户端通信，并利用GPT模型提供智能对话和命令执行功能。服务器能够处理来自游戏的各种事件和命令，并返回相应的游戏信息。项目的核心功能包括处理WebSocket连接、订阅游戏事件、执行游戏命令、与GPT模型交互以及管理游戏状态信息。

核心功能函数#

`main()`#

描述：服务器的主入口点，启动WebSocket服务器并设置周期性更新。
逻辑：
1. 启动WebSocket服务器，监听指定的IP和端口。
2. 调用periodic_update()函数定期更新游戏信息。

`periodic_update()`#

描述：定期更新所有已连接客户端的游戏信息。
逻辑：
1. 每隔10秒清理旧数据并获取新的游戏信息。
2. 调用clear_old_data()和get_game_information()函数。

`handle_connection(websocket, path)`#

描述：处理新的WebSocket连接。
参数：
- websocket: WebSocket连接对象
- path: 连接路径
逻辑：
1. 为新连接生成UUID并初始化相关信息。
2. 发送欢迎消息。
3. 订阅游戏事件。
4. 处理来自客户端的消息并调用相应的处理函数。

`handle_event(websocket, data, conversation)`#

描述：处理来自游戏的传入事件。
参数：
- websocket: WebSocket连接对象
- data: 事件数据
- conversation: GPT对话对象
逻辑：
1. 根据事件类型调用相应的处理函数，如handle_player_message()、handle_command_response()和handle_event_message()。

消息处理函数#

`handle_player_message(websocket, data, conversation)`#

描述：处理玩家消息并执行相应的命令。
参数：
- websocket: WebSocket连接对象
- data: 消息数据
- conversation: GPT对话对象
逻辑：
1. 解析玩家消息以提取命令和内容。
2. 根据命令调用相应的处理函数，如登录验证、GPT聊天、执行命令等。

`handle_command_response(websocket, data)`#

描述：处理命令响应。
参数：
- websocket: WebSocket连接对象
- data: 响应数据
逻辑：
1. 解析命令响应并更新游戏状态信息。
2. 记录命令日志。

`handle_event_message(websocket, data)`#

描述：处理事件消息，如玩家位置更新。
参数：
- websocket: WebSocket连接对象
- data: 事件数据
逻辑：
1. 解析事件数据并更新玩家位置信息。

GPT相关函数#

`gpt_main(conversation, player_prompt)`#

描述：向GPT模型发送提示并返回响应。
参数：
- conversation: GPT对话对象
- player_prompt: 用户的输入提示
逻辑：
1. 调用GPT模型生成响应。
2. 返回GPT的响应消息。

`handle_gpt_chat(websocket, content, conversation)`#

描述：处理GPT聊天请求。
参数：
- websocket: WebSocket连接对象
- content: 聊天内容
- conversation: GPT对话对象
逻辑：
1. 调用gpt_main()生成GPT响应。
2. 发送GPT响应到游戏客户端。

`handle_gpt_script(websocket, content, conversation)`#

描述：处理GPT脚本请求。
参数：
- websocket: WebSocket连接对象
- content: 脚本内容
- conversation: GPT对话对象
逻辑：
1. 调用gpt_main()生成GPT响应。
2. 发送脚本数据到游戏客户端。

`handle_gpt_save(websocket, conversation)`#

描述：保存GPT对话并重启对话。
参数：
- websocket: WebSocket连接对象
- conversation: GPT对话对象
逻辑：
1. 保存当前对话状态。
2. 重启对话并通知客户端。

命令执行函数#

`run_command(websocket, command)`#

描述：执行游戏命令。
参数：
- websocket: WebSocket连接对象
- command: 要执行的命令
逻辑：
1. 构建命令消息并发送到游戏客户端。
2. 记录待响应的命令。

`handle_run_command(websocket, content)`#

描述：处理运行命令请求。
参数：
- websocket: WebSocket连接对象
- content: 命令内容
逻辑：
1. 调用run_command()执行命令。

`handle_script_run_command(websocket, content)`#

描述：处理脚本运行命令请求。
参数：
- websocket: WebSocket连接对象
- content: 脚本命令内容
逻辑：
1. 调用send_script_data()发送脚本命令。

`send_script_data(websocket, content, messageid="server:data")`#

描述：向游戏发送脚本数据。
参数：
- websocket: WebSocket连接对象
- content: 脚本内容
- messageid: 消息ID（默认为”server”）
逻辑：
1. 构建脚本消息并发送到游戏客户端。

游戏信息函数#

`gpt_game_weather(websocket, dimension)`#

描述：检索指定维度的当前天气。
参数：
- websocket: WebSocket连接对象
- dimension: 游戏维度
逻辑：
1. 获取并返回当前维度的天气信息。

`gpt_game_players(websocket)`#

描述：检索游戏中所有玩家的信息。
参数：
- websocket: WebSocket连接对象
逻辑：
1. 获取并返回所有玩家的信息。

`gpt_get_time(websocket, dimension)`#

描述：检索当前游戏时间和天数。
参数：
- websocket: WebSocket连接对象
- dimension: 游戏维度
逻辑：
1. 获取并返回当前游戏时间和天数。

`gpt_run_command(websocket, commands)`#

描述：使用gpt智能运行命令。
参数：
- websocket: WebSocket连接对象
- commands: 要执行的命令列表
逻辑：
1. 调用run_command()执行命令。

`gpt_world_entity(websocket, entityid)`#

描述：检索特定实体的信息。
参数：
- websocket: WebSocket连接对象
- entityid: 实体ID
逻辑：
1. 获取并返回特定实体的信息。

`gpt_player_inventory(websocket, player_name=None)`#

描述：检索特定玩家或所有玩家的物品栏。
参数：
- websocket: WebSocket连接对象
- player_name: 玩家名称（可选）
逻辑：
1. 获取并返回特定玩家或所有玩家的物品栏信息。

`gpt_get_commandlog(websocket)`#

描述：检索命令执行日志。
参数：
- websocket: WebSocket连接对象
逻辑：
1. 获取并返回命令执行日志。

实用函数#

`send_data(websocket, message)`#

描述：通过WebSocket连接发送数据。
参数：
- websocket: WebSocket连接对象
- message: 要发送的消息
逻辑：
1. 将消息转换为JSON格式并发送到WebSocket连接。

`send_game_message(websocket, message)`#

描述：向游戏聊天发送格式化消息。
参数：
- websocket: WebSocket连接对象
- message: 要发送的消息
逻辑：
1. 格式化消息并发送到游戏聊天。

`subscribe_events(websocket)`#

描述：订阅游戏事件。
参数：
- websocket: WebSocket连接对象
逻辑：
1. 构建订阅消息并发送到游戏客户端。

`parse_message(message)`#

描述：解析玩家消息以提取命令和内容。
参数：
- message: 来自玩家的原始消息
逻辑：
1. 检查消息中是否包含预定义命令。
2. 返回命令和内容。

`handle_data_part(message, connection_uuid, data_type, other_message=None)`#

描述：处理来自游戏的部分数据消息。
参数：
- message: 部分数据消息
- connection_uuid: 连接UUID
- data_type: 正在接收的数据类型
- other_message: 附加消息信息（可选）
逻辑：
1. 解析数据部分并存储。
2. 检查是否接收到所有数据部分，若是则组合并解析完整数据。

`handle_display_command_log(websocket)`#

描述：显示命令日志。
参数：
- websocket: WebSocket连接对象
逻辑：
1. 获取并显示命令执行日志。

`clear_old_data(websocket, connection_uuid)`#

描述：清理旧的游戏信息数据。
参数：
- websocket: WebSocket连接对象
- connection_uuid: 连接UUID
逻辑：
1. 清理GameInformation对象中的临时数据。

`get_game_information(websocket, connection_uuid)`#

描述：获取游戏信息。
参数：
- websocket: WebSocket连接对象
- connection_uuid: 连接UUID
逻辑：
1. 发送游戏信息查询命令。
2. 更新游戏信息。

认证函数#

`auth.verify_password(content)`#

描述：验证登录密码。
参数：
- content: 要验证的密码
逻辑：
1. 检查密码是否正确。

`auth.generate_token()`#

描述：生成新的认证令牌。
逻辑：
1. 生成新的随机令牌。

`auth.save_token(connection_uuid, token)`#

描述：为连接保存认证令牌。
参数：
- connection_uuid: 连接UUID
- token: 认证令牌
逻辑：
1. 将令牌与连接UUID关联并存储。

`auth.verify_token(token)`#

描述：验证认证令牌。
参数：
- token: 要验证的令牌
逻辑：
1. 检查令牌是否有效。

`auth.get_stored_token(connection_uuid)`#

描述：获取存储的认证令牌。
参数：
- connection_uuid: 连接UUID
逻辑：
1. 返回存储的令牌。

`auth.is_token_valid(connection_uuid)`#

描述：检查令牌是否有效。
参数：
- connection_uuid: 连接UUID
逻辑：
1. 检查与连接UUID关联的令牌是否有效。

介绍自定义组件

Wed, 14 Aug 2024 00:00:00 GMT

Note

原文：微软文档

日期：2024 年 8 月 14 日

翻译：rice_awa

源项目许可证

介绍自定义组件#

自定义组件是一种将方块和物品的 JSON 配置直接连接到脚本功能的新方式。这种新概念允许在方块和物品之间组合和重用脚本功能，同时确保脚本仅针对特定的方块和物品运行。

这种新模式结合了一种更结构化的方式来监听方块和物品事件，同时获得脚本中的所有功能，并确保这些事件与当前脚本事件在相同的约束下运行。

如果你想开始使用自定义组件构建附加组件，请参阅我们的自定义组件教程。

结构#

这个新特性被称为自定义组件，因为脚本以类似于附加内置 Minecraft 组件的方式连接到给定的方块或物品的 JSON。因此，该特性既有 JSON 方面的内容，也有脚本方面的内容。

脚本 API#

从脚本 API 开始，我们为方块引入了两个新的主要接口：BlockTypeRegistry 和 BlockCustomComponent。（注意：在 1.21.0 之后的 Minecraft 预览版本中，BlockTypeRegistry 被称为 BlockComponentRegistry）BlockTypeRegistry 包含一个用于按名称注册新自定义组件的方法：

1
/**
2
 * @beta
3
 * 提供用于注册方块自定义组件的功能。
4
 */
5
export class BlockTypeRegistry {
6
  /**
7
   * @remarks
8
   * 注册一个可以在方块 JSON 配置中使用的方块自定义组件。
9
   *
10
   * @param name
11
   * 表示此自定义组件的 ID。必须有命名空间。此 ID 可以在方块的 JSON 配置中的 'minecraft:custom_components' 方块组件下指定。
12
   * @param customComponent
13
   * 事件函数的集合，当使用此自定义组件 ID 的方块上发生事件时将调用这些函数。
14
   */
15
  registerCustomComponent(name: string, customComponent: BlockCustomComponent): void
16
}

显示更多显示更少

脚本中的自定义组件是名称/ID 与由事件表示的一组功能的关联。可以监听的事件在第二个接口 BlockCustomComponent 中指定。

1
/**
2
 * @beta
3
 * 包含为方块引发的一组事件。此对象必须使用 BlockRegistry 绑定。
4
 */
5
export interface BlockCustomComponent {
6
  /**
7
   * @remarks
8
   * 当实体踩在绑定此自定义组件的方块上时将调用此函数。
9
   *
10
   */
11
  onStepOn?: (arg: BlockComponentStepOnEvent) => void
12
}

通过脚本，你可以通过监听新的实验性 worldInitialize before 事件来访问 BlockTypeRegistry。所有自定义组件的注册必须在 worldInitialize 期间进行，因为此功能直接附加到 JSON 中的方块初始化。从此事件中，你可以调用 registerCustomComponent，使用唯一的命名空间名称和实现 BlockCustomComponent 接口的对象来注册该组件。一旦组件注册成功，任何使用此组件的方块都会在相关事件中调用你的对象的回调。

以下是显示此注册的小代码示例：

1
world.beforeEvents.worldInitialize.subscribe((initEvent) => {
2
  initEvent.blockTypeRegistry.registerCustomComponent('content:turn_to_air', {
3
    onStepOn: (e) => {
4
      e.block.setPermutation(BlockPermutation.resolve(MinecraftBlockTypes.Air))
5
    },
6
  })
7
})

在上述示例中，注册了一个名为 content:turn_to_air 的自定义组件，该组件监听 onStepOn 事件。也可以将 JavaScript 类注册为自定义组件；唯一重要的是遵循 BlockCustomComponent 接口。以下是使用类模式的示例。

1
class TurnToAirComponent implements BlockCustomComponent {
2
  constructor() {
3
    this.onStepOn = this.onStepOn.bind(this)
4
  }
5

6
  onStepOn(e: BlockComponentStepOnEvent): void {
7
    e.block.setPermutation(BlockPermutation.resolve(MinecraftBlockTypes.Air))
8
  }
9
}
10

11
world.beforeEvents.worldInitialize.subscribe((initEvent) => {
12
  initEvent.blockTypeRegistry.registerCustomComponent(
13
    'content:turn_to_air',
14
    new TurnToAirComponent()
15
  )
16
})

显示更多显示更少

根据你的附加组件或世界的需求，可以选择你喜欢的模式！它们在功能上是相同的。需要注意的是，所有事件通知都是无状态的，事件参数会告知你它们在世界中涉及哪个具体的方块。

JSON#

注册到特定名称的自定义组件后，就需要将其附加到自定义方块中。在自定义方块的 JSON 中的 components 键下，有一个新的 minecraft:custom_components 键，可以在其中注册自定义组件。自定义组件在这里以有序数组的形式列出。此数组允许你控制注册的自定义组件在特定事件中被通知的顺序。以下是注册我们的 content:turn_to_air 自定义组件的示例。

1
    "minecraft:block": {
2
        "description": {
3
            "identifier": "content:my_block"
4
        },
5
        // 基础组件
6
        "components": {
7
            "minecraft:custom_components": ["content:turn_to_air"],
8
            "minecraft:loot": "loot_tables/blocks/my_block.json",

在上述示例中，自定义组件与其他组件（如战利品表）一起附加。如果注册了多个自定义组件，则对于每种类型的事件，事件将按此数组中的顺序发送给自定义组件。

也可以将自定义组件添加到组件键下的每个特定排列中。然而，重要的是要注意，排列中的自定义组件数组完全替换了基础组件列表中的数组。同一个自定义组件也可以在多个文件中使用。例如，这个 content:turn_to_air 组件可以在多个自定义方块中重用，从而实现轻松对齐和组合行为。此外，一个行为包中注册的自定义组件可以在另一个行为包中使用。

工作流程#

在编写自定义组件及其对应的脚本代码时，你可以使用热重载的全部功能，在世界中迭代你的更改。

当对 JSON 和/或新自定义组件的注册进行更改时，需要退出世界并重新进入以查看更改的效果。

一旦进入脚本，你的回调可以像今天的任何其他脚本一样使用脚本 API 中的任何 API，并具有相同的约束。

开始构建自定义组件#

如果你想开始使用自定义组件构建附加组件，请访问自定义组件教程。需要注意的是，在 1.21.0 之后的 Minecraft 预览版本中，BlockTypeRegistry 被称为 BlockComponentRegistry。

使用自定义组件构建

Wed, 14 Aug 2024 00:00:00 GMT

Note

原文：微软文档

日期：2024 年 8 月 14 日

翻译：rice_awa

源项目许可证

使用自定义组件进行构建#

创建一个带有自定义组件的附加包#

Note

自定义组件功能目前处于预览阶段，可通过测试版API使用，但计划在未来的Minecraft版本中包含在“稳定API”中——可能是1.21.10版本。我们建议您在尝试此示例时使用最新版本的Minecraft Preview。

自定义方块和物品使用各种组件，在其定义中声明，以增强方块或物品的行为。

到目前为止，所有组件都是内置于Minecraft中的，通过各种参数来控制组件的行为。使用自定义组件，现在处于预览阶段，并将在即将发布的Minecraft版本中更广泛地提供，您可以结合脚本为方块和物品定义自己的行为！在本教程中，我们将通过添加新的草莓作物和草莓物品，制作一个小的方块和物品示例。草莓植物将具有这样的行为：如果在成熟时没有被采摘，它们会变坏。您必须把握好时机才能获得新鲜的草莓，在这个示例中，您将看到管理作物生长速度的方块组件以及自定义物品效果。

草莓农场和一些腐烂的草莓

您可以在github.com/microsoft/minecraft-scripting-samples上找到此示例的源代码。

前提条件#

在开始之前，您应该已经完成了附加包入门教程、行为包介绍教程和脚本介绍教程。

您需要熟悉附加包文件夹的结构、行为包应包含的必需文件以及如何在行为包中使用脚本。

一些其他有用的资源是如何在您的附加包中制作方块和物品：

创建自定义染料方块

物品自定义组件#

草莓物品将利用自定义组件为食用它的玩家提供夜视效果。首先让我们制作草莓物品本身。

1
{
2
  "format_version": "1.21.10",
3
  "minecraft:item": {
4
    "description": {
5
      "menu_category": {
6
        "group": "itemGroup.name.crop",
7
        "category": "nature"
8
      },
9
      "identifier": "example:strawberry"
10
    },
11
    "components": {
12
      "minecraft:icon": "strawberry",
13
      "minecraft:max_stack_size": 64,
14
      "minecraft:use_modifiers": {
15
        "use_duration": 1.6,
16
        "movement_modifier": 0.35
17
      },
18
      "minecraft:food": {
19
        "can_always_eat": true,
20
        "nutrition": 1,
21
        "saturation_modifier": 0.5
22
      },
23
      "minecraft:use_animation": "eat"
24
    }
25
  }
26
}

显示更多显示更少

向物品添加自定义组件#

要向物品添加自定义组件，请向物品添加一个minecraft:custom_components组件，该组件包含一个字符串数组。

在这个数组中，字符串是您要添加的组件的名称。当事件发生时，组件将运行一些脚本，并且这些脚本将按照您在JSON中定义的顺序运行。这意味着一个物品可以以不同于另一个物品的顺序运行相同的组件。对于我们的草莓，我们只需要一个组件，但对于您自己的物品，您可以向数组中添加更多自定义组件。

1
"minecraft:custom_components": [
2
    "example:add_night_vision_on_consume"
3
]

您为自定义组件选择的名称需要一个命名空间。在上面的代码中，命名空间是example，组件名称是add_night_vision_on_consume。

在脚本中注册物品自定义组件#

现在我们的物品已经配置为具有自定义组件，我们需要在脚本中注册该组件的行为。我们想要的行为是，当您食用草莓时，玩家会获得一段时间的夜视效果。首先，我们使用与JSON组件中定义的相同名称将我们的组件注册到ItemComponentRegistry，并提供该组件正在监听的事件列表。在这种情况下，我们将监听物品自定义组件的onConsume事件，当玩家食用物品时将运行我们的代码。然后我们可以将夜视效果添加到玩家身上，我们的自定义组件现在可以使用了。

1
import { ItemComponentConsumeEvent, world } from '@minecraft/server'
2

3
world.beforeEvents.worldInitialize.subscribe((initEvent) => {
4
  initEvent.itemComponentRegistry.registerCustomComponent('example:add_night_vision_on_consume', {
5
    onConsume(arg: ItemComponentConsumeEvent) {
6
      arg.source.addEffect('minecraft:night_vision', 600)
7
    },
8
  })
9
})

注意，组件代码和名称并没有引用草莓物品本身。您可以在具有类似行为的多个物品上重复使用组件。

Note

截至撰写本文时，自定义组件仍处于预览阶段。因此，您需要在行为包的manifest.json的依赖项部分使用-beta脚本模块。

1
  "dependencies": [
2
    {
3
      "module_name": "@minecraft/server",
4
      "version": "1.13.0-beta"
5
    }
6
  ]

方块自定义组件#

方块自定义组件的工作方式与物品自定义组件非常相似。首先我们需要我们的方块定义：

1
{
2
  "format_version": "1.21.10",
3
  "minecraft:block": {
4
    "description": {
5
      "identifier": "example:strawberry_crop",
6
      "states": {
7
        "starter:crop_age": [0, 1, 2, 3, 4]
8
      }
9
    },
10
    "permutations": [
11
      {
12
        "condition": "query.block_state('starter:crop_age') == 4",
13
        "components": {
14
          "minecraft:loot": "loot_tables/strawberry_grown_crop.json"
15
        }
16
      }
17
    ],
18
    "components": {
19
      "minecraft:geometry": "geometry.starter_crop_geo",
20
      "minecraft:loot": "loot_tables/strawberry_seed.json",
21
      "minecraft:collision_box": false,
22
      "minecraft:placement_filter": {
23
        "conditions": [
24
          {
25
            "allowed_faces": ["up"],
26
            "block_filter": ["minecraft:farmland"]
27
          }
28
        ]
29
      },
30
      "tag:minecraft:crop": {}
31
    }
32
  }
33
}

显示更多显示更少

向方块添加自定义组件#

与物品自定义组件类似，我们在方块JSON中使用minecraft:custom_components组件来定义此方块具有哪些自定义组件。在这种情况下，我们将添加两个不同的组件定义：一个在方块的基础部分，另一个在排列中。当方块排列和基础方块都使用minecraft:custom_components组件时，只有排列中列出的组件将运行其脚本代码。这允许您重新排序、删除或向方块的特定排列添加新的自定义组件。由于草莓作物的前四个排列（年龄0-3）都使用相同的自定义组件，我们可以将其放在基础方块的组件列表中。最后一个排列（年龄4）将具有一些额外的功能，因此我们可以收获完全成熟的草莓，因此它需要自己的minecraft:custom_components来覆盖基础方块中的组件。

1
{
2
  "format_version": "1.21.10",
3
  "minecraft:block": {
4
    "description": {
5
      "identifier": "example:strawberry_crop",
6
      "states": {
7
        "starter:crop_age": [0, 1, 2, 3, 4]
8
      }
9
    },
10
    "permutations": [
11
      {
12
        "condition": "query.block_state('example:crop_age') == 4",
13
        "components": {
14
          "minecraft:loot": "loot_tables/strawberry_grown_crop.json"
15
        },
16
        "minecraft:custom_components": ["example:crop_harvest"]
17
      }
18
    ],
19
    "components": {
20
      "minecraft:geometry": "geometry.example_crop_geo",
21
      "minecraft:loot": "loot_tables/strawberry_seed.json",
22
      "minecraft:collision_box": false,
23
      "minecraft:placement_filter": {
24
        "conditions": [
25
          {
26
            "allowed_faces": ["up"],
27
            "block_filter": ["minecraft:farmland"]
28
          }
29
        ]
30
      },
31
      "tag:minecraft:crop": {},
32
      "minecraft:custom_components": ["example:crop_grow"]
33
    }
34
  }
35
}

显示更多显示更少

在脚本中注册方块自定义组件#

与物品类似，我们在脚本中注册组件，并提供组件正在监听的事件列表以及事件触发时应运行的行为。对于物品，我们使用ItemComponentRegistry来完成此操作；对于方块，我们使用BlockComponentRegistry（或在Minecraft 1.21.0或更早版本中使用BlockTypeRegistry）。在这种情况下，我们有两个组件需要填写。上面的物品示例展示了如何通过在注册语句中放置行为来完成此操作。这两个组件将展示两种不同的组织代码的方式。

“example” 组件#

此组件旨在通过监听方块自定义组件的onRandomTick事件来生长作物，并将方块的排列更改为下一个年龄。此组件通过为事件提供一个运行函数来注册，而之前的物品自定义组件示例在其代码中具有其行为。

1
import { BlockComponentRandomTickEvent, world } from '@minecraft/server'
2

3
function cropGrowRandomTick(event: BlockComponentRandomTickEvent) {
4
  const age = event.block.permutation.getState('example:crop_age')
5
  if (age === undefined || typeof age !== 'number') {
6
    return
7
  } else if (age === 4) {
8
    return // fully grown
9
  }
10

11
  event.block.setPermutation(event.block.permutation.withState('example:crop_age', age + 1))
12
}
13

14
world.beforeEvents.worldInitialize.subscribe((initEvent) => {
15
  initEvent.blockTypeRegistry.registerCustomComponent('example:crop_grow', {
16
    onRandomTick: cropGrowRandomTick,
17
  })
18
})

显示更多显示更少

“example” 组件#

作物生长组件仅存在于准备收获的成品作物上。此组件将允许玩家与方块互动以收获草莓，而无需破坏方块。然后它通过将方块排列更改回第一个生长阶段来“重新种植”草莓。此组件通过创建一个实现BlockCustomComponent对象的新类来注册，为您提供第三种注册组件的方式。物品也可以使用相同的方法和ItemCustomComponent对象。

1
import { BlockCustomComponent, BlockComponentPlayerInteractEvent, world } from '@minecraft/server'
2

3
class BlockCropHarvestComponent implements BlockCustomComponent {
4
  onPlayerInteract(event: BlockComponentPlayerInteractEvent) {
5
    if (event.player === undefined) {
6
      return
7
    }
8

9
    const blockPos = event.block.location
10
    event.dimension.runCommand(
11
      'loot spawn ' +
12
        blockPos.x +
13
        ' ' +
14
        blockPos.y +
15
        ' ' +
16
        blockPos.z +
17
        ' loot strawberry_grown_crop'
18
    )
19
    event.block.setPermutation(event.block.permutation.withState('example:crop_age', 0))
20
  }
21
}
22

23
world.beforeEvents.worldInitialize.subscribe((initEvent) => {
24
  initEvent.blockTypeRegistry.registerCustomComponent(
25
    'example:crop_harvest',
26
    new BlockCropHarvestComponent()
27
  )
28
})

显示更多显示更少

恭喜！您现在有一个使用自定义组件的方块和物品。请查看我们的自定义组件示例在Minecraft脚本示例库。

为我的世界基岩版构建基于WebSocket的AI助手

Tue, 13 Aug 2024 00:00:00 GMT

为我的世界基岩版构建基于WebSocket的AI助手#

在游戏和人工智能不断发展的世界中，将两者结合可以带来令人兴奋和创新的项目。本博客文章将探讨一个独特的项目，该项目使用WebSockets和GPT模型将AI助手集成到我的世界基岩版中。

项目概述#

该项目创建了一个WebSocket服务器，作为我的世界基岩版和由GPT模型驱动的AI助手之间的桥梁。该系统允许玩家在游戏中与AI交互，执行命令，并接收有关游戏世界的实时信息。

关键组件#

WebSocket服务器：处理来自我的世界客户端的连接并管理通信。
GPT API对话：与GPT模型交互以生成响应。
游戏信息管理：跟踪游戏状态、玩家信息等。
命令处理：执行游戏内命令并处理响应。

实现细节#

WebSocket服务器#

服务器使用Python的asyncio和websockets库实现。它处理多个客户端连接，并在游戏和AI助手之间路由消息。

1
async def handle_connection(websocket, path):
2
    connection_uuid = str(uuid.uuid4())
3
    websocket.uuid = connection_uuid
4
    print(f"客户端: {connection_uuid} 已连接")
5

6
    # 初始化对话和游戏信息
7
    conversation = GPTAPIConversation(api_key, api_url, model, functions, functions_map, websocket, system_prompt=system_prompt, enable_logging=True)
8
    server_state.information[connection_uuid] = GameInformation()
9
    server_state.connections[connection_uuid] = websocket
10

11
    # 主连接循环
12
    try:
13
        await send_data(websocket, {"Result": "true"})
14
        await subscribe_events(websocket)
15

16
        async for message in websocket:
17
            data = json.loads(message)
18
            await handle_event(websocket, data, conversation)
19

20
    # 处理断开连接和清理
21
    except websockets.exceptions.ConnectionClosed:
22
        print(f"客户端 {connection_uuid} 连接已关闭")
23
    finally:
24
        # 清理代码

显示更多显示更少

GPT API对话#

GPTAPIConversation类管理与GPT模型的交互。它处理消息历史、函数调用，并维护对话上下文。

1
class GPTAPIConversation:
2
    def __init__(self, api_key, api_url, model, functions, functions_map, websocket, system_prompt="", enable_logging=False):
3
        # 初始化代码
4

5
    async def call_gpt(self, prompt):
6
        # 调用GPT API并处理响应的代码
7

8
    async def handle_response(self, result):
9
        # 处理GPT响应，包括函数调用

游戏信息管理#

该项目使用数据类来组织游戏相关信息：

1
@dataclass
2
class GameInformation:
3
    game_weather: str = ''
4
    game_time: str = ''
5
    game_day: str = ''
6
    players: str = ''
7
    player_inventory: Dict[str, Any] = field(default_factory=dict)
8
    need_entityid: str = ''
9
    entity_info: str = ''
10
    player_info: Dict[str, Any] = field(default_factory=dict)
11
    player_transform_messages: Dict[str, PlayertransformInfo] = field(default_factory=dict)
12
    commandResponse_log: Dict[str, str] = field(default_factory=dict)

命令处理#

该项目包括在我的世界中执行命令并处理响应的功能：

1
async def run_command(websocket, command):
2
    # 向我的世界发送命令的代码
3

4
async def handle_command_response(websocket, data):
5
    # 处理命令响应并更新游戏信息

AI助手功能#

AI助手可以执行各种任务，包括：

与玩家聊天
执行游戏命令
提供有关游戏世界的信息（天气、时间、玩家）
管理玩家库存
与游戏内实体交互

挑战与解决方案#

消息分片：来自游戏的大型消息被分成多个部分。系统在处理前重新组装这些部分。
异步操作：该项目广泛使用asyncio来同时处理多个连接和操作。
状态管理：ServerState类跟踪连接、游戏信息和待处理的命令。
安全性：该项目实现了基本的身份验证系统来控制对AI功能的访问。

结论#

这个项目展示了将AI助手集成到游戏环境中的潜力。通过结合WebSockets、GPT模型和我的世界的脚本功能，我们创建了一个增强游戏体验并为玩家-AI交互开辟新可能性的系统。

未来的改进可能包括更高级的自然语言处理、扩展游戏世界交互，以及与其他游戏系统的集成。代码结构还允许轻松扩展以支持使用WebSocket通信的其他游戏或平台。

注意：本文档中的代码片段和示例仅用于演示目的，可能需要根据您的具体需求进行修改和调整。

Building by claude#

Firefly 简单使用指南

Sat, 09 Sep 2023 00:00:00 GMT

这个博客模板是基于 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。

文章文件的放置位置#

您的文章文件应放置在 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 会自动转换为小写

Sample .md file

Tue, 08 Mar 2016 00:00:00 GMT

A sample post with markdown.

Inline Highlighting#

Sample of inline highlighting sum = parseInt(num1) + parseInt(num2)

Code Blocks#

Some Javascript code

1
var num1, num2, sum
2
num1 = prompt('Enter first number')
3
num2 = prompt('Enter second number')
4
sum = parseInt(num1) + parseInt(num2) // "+" means "add"
5
alert('Sum = ' + sum) // "+" means combine into a string

Some Python code 🐍

1
def fib():
2
    a, b = 0, 1
3
    while True:            # First iteration:
4
        yield a            # yield 0 to start with and then
5
        a, b = b, a + b    # a will now be 1, and b will also be 1, (0 + 1)
6

7
for index, fibonacci_number in zip(range(10), fib()):
8
     print('{i:3}: {f:3}'.format(i=index, f=fibonacci_number))

Firefly 代码块示例

Sat, 03 Jan 1970 00:00:00 GMT

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

表达性代码#

语法高亮#

语法高亮

常规语法高亮#

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

编辑器和终端框架#

编辑器和终端框架

代码编辑器框架#

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 数学公式示例

Fri, 02 Jan 1970 00:00:00 GMT

本文展示了 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)#

CHX4+2 OX2→COX2+2 HX2O\ce{CH4 + 2O2 -> CO2 + 2H2O}CHX4+2OX2COX2+2HX2O

MDX 格式文章示例

Fri, 02 Jan 1970 00:00:00 GMT

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>

火箭发射！

使用 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>

这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。

简单的变量导出#

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

3
今年是 {year} 年。

今年是 2026 年。

更多信息，请查看 MDX 文档

Markdown 扩展功能

Thu, 01 Jan 1970 00:00:00 GMT

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。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress"
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 语法列表

支持以下类型的提醒框：note tip important warning caution

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

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

9
:::important
10
用户成功所必需的关键信息。
11
:::
12

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

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

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

显示更多显示更少

剧透#

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

内容被隐藏了哈哈！

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

Markdown Mermaid 图表

Thu, 01 Jan 1970 00:00:00 GMT

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 教程

Thu, 01 Jan 1970 00:00:00 GMT

这是一个展示如何编写 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**

***

在文章中嵌入视频

Thu, 01 Jan 1970 00:00:00 GMT

只需从 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>

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