Dan's Blog

Cloudflare Pages Redirects Working but GSC Not Recognizing? Migration Fix & Bulk Redirects Solution

Fri, 20 Mar 2026 00:00:00 GMT

Introduction

When I migrated my site to a new domain using GSC, I ran into a frustrating issue. I had already set up 301 redirects, but GSC just wouldn’t recognize them. I kept seeing the old pages.dev domain still stealing my traffic. Then I found a solution from a blog called Codemzy—and it actually worked.

Background

When moving a site from *.pages.dev to a custom domain, passing SEO ranking is the key concern. According to the official docs, the ideal approach is using 301 permanent redirects, so Google knows the original URL has permanently moved to the new address and passes the ranking authority over.

Here’s the scenario:

Source: https://dansblog.pages.dev
Target: https://danarnoux.com
Expected: Both browser and search engines receive 301 status code

The Problem

After configuring redirects, testing revealed:

Browser works fine - Visiting dansblog.pages.dev/any-path automatically redirects to danarnoux.com/any-path, seamless for users
GSC error - Google Search Console reports many URLs returning non-301 status codes, migration verification fails
cURL test oddities - Some tools detect status codes that don’t match expectations

Very strange: user access works perfectly, but Google just won’t acknowledge it.

Failed Solutions

Solution 1: _redirects File

Tried configuring in public/_redirects:

https://dansblog.pages.dev/* https://danarnoux.com/:splat 301

Result: Browser redirect works, but GSC still doesn’t recognize it.

Root cause analysis (inference based on Cloudflare official documentation):

1.1 Official Documentation References

Bulk Redirects Docs: https://developers.cloudflare.com/rules/url-forwarding/bulk-redirects/

“Bulk Redirects allow you to define URL redirects at the account level and have them executed at the edge.”

Redirect Rules Docs: https://developers.cloudflare.com/rules/url-forwarding/

Pages _redirects Docs: https://developers.cloudflare.com/pages/platform/redirects/

“You can define redirects by adding a _redirects file to your project.”

How Pages Works: https://developers.cloudflare.com/pages/platform/how-pages-works/

“Cloudflare Pages serves your site through Cloudflare’s global network.”

1.2 Technical Interpretation

According to the documentation, the two redirect mechanisms are fundamentally different:

Mechanism	Processing Level	Execution Location
Pages _redirects	Project-level (injected at build)	Pages Platform
Bulk Redirects	Account-level	Edge Network

_redirects is part of your project, defined via public/_redirects file, processed by the Pages platform at build time
Bulk Redirects are a separate Rules system, executed at edge nodes globally, with higher priority than Pages-level config

1.3 Inference

Based on Cloudflare’s official documentation, we can confirm:

_redirects belongs to Pages project-level redirect configuration
Bulk Redirects belong to the Rules system, executed directly on Cloudflare’s Edge network

With that context, here’s a somewhat conservative inference:

GSC, when performing site migration detection, may more readily recognize 301 redirects returned directly from the Edge layer. For redirects implemented at the Pages layer, it may not consistently recognize them.

Important to note:

Neither Cloudflare nor Google has explicitly explained GSC’s judgment logic
The above conclusions are based solely on documentation structure and actual test results

👉 In practice, Bulk Redirects can reliably pass GSC migration verification.

Solution 2: Worker Approach

Tried writing a Cloudflare Worker to handle redirects.

Result: Works, but has instability risks—Workers can fail due to limits, config changes, or other issues.

The Fix: Bulk Redirects

The final solution uses Cloudflare Bulk Redirects.

Important: Bulk Redirects has a two-step structure:

First create a Redirect List (rule data)
Then create a Redirect Rule (activates the rules)

Step 1: Access Bulk Redirects

Go to Cloudflare Dashboard:

Select your domain (e.g., danarnoux.com)
On the left sidebar: Rules → Redirect Rules
Switch to Bulk Redirects tab

Step 2: Create Bulk Redirect List (Do This First)

Click:

Create Bulk Redirect List

Fill in:

List name: e.g., pages-dev-redirect

Step 3: Add Rules to the List

Add one rule:

Field	Value
Source URL	`https://dansblog.pages.dev/*`
Target URL	`https://danarnoux.com/$1`
Status	301 (or use 302 for testing first)
Preserve query string	Optional
Subpath matching	ON
Preserve path suffix	ON

Key points:

Use * to match all paths
Use $1 to preserve the original path
Recommend using 302 first to test, then switch to 301 when confirmed

note

In “Add URLs”, click “Or, Manually add URL redirects”, then remember to click “Edit parameters”.

About the options:

Subpath matching / Preserve path suffix: Recommend turning these on, otherwise paths may not pass correctly
Preserve query string: Whether to enable depends on your needs (e.g., if you need to keep URL parameters). Disabling it still allows migration to complete normally.

Step 4: Create Bulk Redirect Rule (Activate the Rules)

Go back to Bulk Redirects page:

Click:

Create Bulk Redirect Rule

Configure:

Rule name: e.g., pages.dev redirect
Redirect using list: Select the List you just created

Step 5: Enable the Rule

After saving, make sure:

Rule status is ✅ Enabled (green)

👉 Note:

If you only create a List without a Rule, it won’t take effect

For reference, check the example in step 1—note that Status shows “Active”

Step 6: Wait for Activation

Click Save / Deploy
Usually takes effect within 1-2 minutes

Summary

The correct flow for Bulk Redirects:

List (define rules) → Rule (enable rules) → Edge execution

Key Difference

Essential difference between Bulk Redirects and _redirects:

Bulk Redirects are processed directly at Cloudflare’s network edge (Edge), without going through the Pages layer
Higher priority, more stable rules
More reliable status code returns

Verification

After configuration, verify using these methods:

1. Browser Test

Visit the original URL directly to confirm redirect works.

2. cURL Test

curl -I https://dansblog.pages.dev/blog/test
# Should return 301 + Location: https://danarnoux.com/blog/test

3. GSC Verification

In Google Search Console, re-verify the migration. After success, you should see a prompt: This site is currently being migrated to [danarnoux.com].

Conclusion

When migrating from *.pages.dev to a custom domain, the _redirects method works fine in browsers, but GSC may not recognize it. According to the documentation, Bulk Redirects execute at the Edge layer, making status code returns more stable and reliable—recommended for direct use.

As for why _redirects isn’t recognized by GSC, neither Cloudflare nor Google has explicitly explained GSC’s specific judgment logic. The above is merely an inference based on documentation structure—no absolute conclusion can be drawn. If you value stability, Bulk Redirects is the safer choice.

Original article from Codemzy: https://www.codemzy.com/blog/cloudflare-pages-dev-redirect

Cloudflare Pages 重定向正常但 GSC 不识别？网站迁移失败与 Bulk Redirects 解决方案

Fri, 20 Mar 2026 00:00:00 GMT

1. 前言

我买了一个新域名后，使用GSC迁移网站的时候很是头疼，明明自己已经做好了重定向301的工作，但是为什么GSC就是不认呢？我还得天天看着旧的pages.dev域名在分我流量，不过，我找到一个叫Codemzy的博客提出了解决方案，参考一下竟然真的有效。

2. 背景

将网站从 *.pages.dev 迁移到自定义域名时，SEO 权重传递是关键问题。按照官方文档，最理想的方式是使用 301 永久重定向，让 Google 知道原 URL 已永久迁移到新地址，从而将排名权重传递给新域名。

本次场景：

源站：https://dansblog.pages.dev
目标：https://danarnoux.com
期望：浏览器和搜索引擎均返回 301 状态码

3. 问题现象

配置重定向后，实际测试发现：

浏览器访问正常 - 输入 dansblog.pages.dev/any-path 会自动跳转到 danarnoux.com/any-path，跳转过程无感知
GSC 报错 - Google Search Console 提示大量 URL 返回非 301 状态码，无法完成迁移验证
cURL 测试异常 - 部分工具检测到的状态码与预期不符

这就很奇怪了：用户访问完全正常，但 Google 就是不认。

4. 错误方案

4.1 _redirects 方案

尝试在 public/_redirects 中配置：

https://dansblog.pages.dev/* https://danarnoux.com/:splat 301

结果：浏览器跳转正常，但 GSC 仍无法识别。

原因分析（基于 Cloudflare 官方文档的推论）：

4.1.1 官方文档引用

Bulk Redirects 文档： https://developers.cloudflare.com/rules/url-forwarding/bulk-redirects/

“Bulk Redirects allow you to define URL redirects at the account level and have them executed at the edge.”

Redirect Rules 文档： https://developers.cloudflare.com/rules/url-forwarding/

Pages _redirects 文档： https://developers.cloudflare.com/pages/platform/redirects/

“You can define redirects by adding a _redirects file to your project.”

Pages 工作原理： https://developers.cloudflare.com/pages/platform/how-pages-works/

“Cloudflare Pages serves your site through Cloudflare’s global network.”

4.1.2 技术解读

根据文档，两种重定向机制存在本质区别：

机制	处理层级	执行位置
Pages _redirects	项目内部（构建时注入）	Pages 平台
Bulk Redirects	账户级别	边缘网络（Edge）

_redirects 是项目的一部分，通过 public/_redirects 文件定义，由 Pages 平台在构建时处理
Bulk Redirects 是独立的 Rules 系统，在全球边缘节点执行，优先级高于 Pages 层面

4.1.3 推论

基于 Cloudflare 官方文档可以确认：

_redirects 属于 Pages 项目内部的重定向配置
Bulk Redirects 属于 Rules 系统，在 Cloudflare 边缘网络（Edge）直接执行

在此基础上，可以做一个相对保守的推测：

GSC 在进行网站迁移检测时，可能更容易识别由 Edge 层直接返回的 301 重定向，而对于 Pages 层内部实现的重定向，不一定能够稳定识别。

需要说明的是：

Cloudflare 和 Google 官方均未明确说明 GSC 的判定逻辑
以上结论仅基于文档结构和实际测试结果

👉 实际效果上，Bulk Redirects 可以稳定通过 GSC 迁移验证。

4.2 Worker 方案

尝试编写 Cloudflare Worker 实现重定向。

结果：可以工作，但存在不稳定性风险——Worker 可能因为超限、配置变更等原因失效。

5. 正确解决方案：Bulk Redirects

最终采用 Cloudflare Bulk Redirects（批量重定向）。

需要注意：Bulk Redirects 的配置是 两步结构：

先创建 Redirect List（规则数据）
再创建 Redirect Rule（让规则生效）

5.1 进入 Bulk Redirects

进入 Cloudflare Dashboard：

选择你的域名（如 danarnoux.com）
左侧进入：Rules → Redirect Rules
切换到 Bulk Redirects

5.2 创建 Bulk Redirect List（先做这一步）

点击：

Create Bulk Redirect List

填写：

List 名称：如 pages-dev-redirect

5.3 在 List 中添加规则

添加一条规则：

字段	值
Source URL	`https://dansblog.pages.dev/*`
Target URL	`https://danarnoux.com/$1`
Status	301（或先用 302 测试）
Preserve query string	可选
Subpath matching	ON
Preserve path suffix	ON

关键点：

* 用于匹配所有路径
$1 用于保留原始路径
建议先使用 302 测试，确认无误后再改为 301

note

在Add URLs，点击 Or,Manually and URL redirects即可，然后记得点击Edit parameters。

关于选项说明：

Subpath matching / Preserve path suffix：建议开启，否则路径可能无法正确传递
Preserve query string：是否开启取决于你的需求（例如是否需要保留 URL 参数），关闭同样可以正常完成迁移

5.4 创建 Bulk Redirect Rule（让规则生效）

回到 Bulk Redirects 页面：

点击：

Create Bulk Redirect Rule

配置：

Rule 名称：如 pages.dev redirect
Redirect using list：选择刚刚创建的 List

5.5 启用规则

保存后，确保：

Rule 状态为 ✅ Enabled（绿色）

👉 注意：

如果没有创建 Rule，仅有 List 是不会生效的

生效例图参考step1，注意Status为Active

5.6 等待生效

点击 Save / Deploy
通常 1~2 分钟内生效

5.7 小结

Bulk Redirects 的正确流程是：

List（定义规则） → Rule（启用规则） → Edge 执行

5.8 关键区别

Bulk Redirects 与 _redirects 的本质区别：

Bulk Redirects 在 Cloudflare 网络边缘（Edge）直接处理，不经过 Pages 层面
优先级更高，规则更稳定
状态码返回更可靠

6. 验证方式

配置完成后，通过以下方式验证：

6.1 浏览器测试

直接访问原 URL，确认跳转正常。

6.2 cURL 测试

curl -I https://dansblog.pages.dev/blog/test
# 应返回 301 + Location: https://danarnoux.com/blog/test

6.3 GSC 验证

在 Google Search Console 中重新验证迁移，成功后应该会出现一个提示 此网站目前正在迁移到 danarnoux.com。

7. 总结

网站从 *.pages.dev 迁移到自定义域名时，_redirects 方法在浏览器端工作正常，但 GSC 可能无法识别。根据官方文档，Bulk Redirects 在 Edge 层执行，状态码返回更稳定可靠，建议直接使用。

至于为什么 _redirects 不被 GSC 识别，官方文档没有明确说明 GSC 的具体判定逻辑，以上仅为基于文档结构的推测，无法给出绝对结论。如果追求稳定性，Bulk Redirects 是更稳妥的选择。

Codemzy的博客原文网址：https://www.codemzy.com/blog/cloudflare-pages-dev-redirect

OpenClaw Windows 卸载教程

Mon, 16 Mar 2026 00:00:00 GMT

前言

如果你不再需要 OpenClaw，可以按照以下步骤将其彻底卸载。虽然很好笑，因为我前几天刚出过部署的教程。

1. 卸载 OpenClaw

OpenClaw 通过 npm 全局安装，卸载非常简单。打开 PowerShell，运行：

npm uninstall -g openclaw

2. 删除配置文件

OpenClaw 会在用户目录下创建配置文件，可以手动删除。

Windows：打开 CMD 或 PowerShell，运行：

rmdir /s /q %USERPROFILE%\.openclaw

Linux / macOS：

rm -rf ~/.openclaw

3. 验证卸载成功

运行以下命令：

openclaw --version

如果提示 command not found 或找不到命令，说明卸载成功。

OpenClaw Windows Uninstall Guide

Mon, 16 Mar 2026 00:00:00 GMT

Introduction

If you no longer need OpenClaw, you can follow these steps to completely uninstall it. It’s kind of funny—I just made a deployment guide a few days ago!

1. Uninstall OpenClaw

OpenClaw is installed globally via npm, so uninstalling is simple. Open PowerShell and run:

npm uninstall -g openclaw

2. Delete Configuration Files

OpenClaw creates a config directory in your user folder. You can delete it manually.

Windows: Open CMD or PowerShell and run:

rmdir /s /q %USERPROFILE%\.openclaw

Linux / macOS:

rm -rf ~/.openclaw

3. Verify Uninstallation

Run the following command:

openclaw --version

If you see command not found or an error saying the command doesn’t exist, the uninstallation was successful.

OpenClaw Windows 安装与配置教程（MiniMax / Qwen / Ollama）

Tue, 10 Mar 2026 00:00:00 GMT

前言

我一直都在思考我到底要不要做一个Openclaw的部署教程，因为Openclaw中文站的内容已经很详细了，但是我意识到大家可能并不知道有这个中文站的存在另外就是跟着这个教程做还是看不懂。最近Openclaw真是在国内的热度简直过热，有点过誉了，一代人有一代人的气功热。但是我还是坚持做一个比较详细的教程你自己部署体验一下，因为一个产品到底怎么样，你自己用体验后才知道、说实话有个自己的贾维斯这种概念还是很吸引人的。

1. 什么是 OpenClaw？

先简单介绍一下，OpenClaw（以前叫 Clawdbot，现在改名前还挺有意思的）是一个开源的 AI Agent 框架。简单来说，你可以把它理解成一个「AI 操作系统」—— 它本身不提供 AI 能力，但它能帮你调用各种大模型，帮你完成各种任务。

和普通的聊天机器人不一样，OpenClaw 能做的事情更多：

操作文件系统
执行命令。
编写和调试代码
搜索信息
接入飞书、Telegram 等通讯工具

你只需要给它配上合适的模型，它就能帮你干活。

2. OpenClaw 工作原理

先理清一个概念：OpenClaw 只是一个「壳」，模型得你自己接入。

工作流程大概是这样的：

你（输入） → OpenClaw → AI 模型 → 返回结果

你可以选择接入：

云端模型：MiniMax、Qwen（阿里云百炼）、OpenAI、Claude 等
本地模型：通过 Ollama 在本地运行的模型

两种方案各有优劣，后面会详细说。

提示：本文档包含专门章节讲解如何配置 Ollama 本地模型，请参见第 5.8 节。

3. 部署方式与模型方案

官方文档：如果想了解更多高级配置，可以参考 OpenClaw 中文文档。

在开始安装之前，先了解两种部署方式和模型方案的选择。

3.1 部署方式说明

OpenClaw 有两种部署方式：

部署方式	说明	适用场景
本地部署	在自己的 Windows 电脑上运行	个人使用、隐私优先、低成本
远程服务器	在云服务器上运行（如 Linux 服务器）	多用户共享、7×24 小时运行

本教程聚焦本地部署——在你自己的 Windows 电脑上运行 OpenClaw。因为存在一个问题，虽然远程服务器部署很方便，厂商都帮你一件配置好了，但是你可能其实想要的是私人电脑管家贾维斯，虽然这会有更多的风险，但你自己会权衡承担的。

3.2 选哪种模型方案？

在开始安装之前，先决定你要用哪种模型方案。这会影响后面的配置步骤。

云端 API（推荐新手）

调用云端模型的 API，按调用量付费（一般都有免费额度）。

模型商	推荐模型	特点
MiniMax	M2.5	性价比高，中文优化好
Qwen	qwen/qwen3-coder / qwen/qwen3-vl	编程能力强，阿里云免费额度够用

qwen3-coder 是阿里推出的编程优化模型。 | OpenAI | GPT-5 系列模型 | 综合能力强 |

优点：不需要显卡，响应快，能力有保障缺点：需要付费（但通常有免费额度）

本地模型（Ollama）

在自己电脑上运行模型，完全免费，但需要硬件配置。

优点：零成本，隐私好缺点：对显卡有要求，响应速度取决于硬件

说实话大部分情况你的电脑是运行不了的，你可以查看一下你电脑的GPU是什么配置，我给实验室的工作站都没有选择Ollama方案，首先的问题就是你不能因为显存够能跑而忽略速度，其次是你想我这配置已经相当的强大了，但我也没选择Ollama方案。选择API方案蛮好的，就是花点钱。

我的建议：新手直接用远程 API，MiniMax 或 Qwen 都不错，配好了 5 分钟就能用上。

3.3 如何选择合适的大模型？

选择大模型主要看以下几个因素：

因素	说明
价格	云端 API 按调用量付费，不同模型价格差异大
速度	响应速度取决于模型大小和网络
上下文长度	能处理多长的文本，越长越贵
编程能力	某些模型专门针对编程优化
推理能力	复杂问题的解决能力

使用 OpenRouter 排行榜

OpenRouter 提供了便捷的模型排行榜，你可以根据以下维度筛选：

性能（Performance）：模型的综合 benchmark 分数
价格（Price）：按输入/输出价格排序
上下文长度（Context Length）：支持的最大 token 数
延迟（Latency）：响应速度

在 OpenRouter 网站上搜索具体模型，可以查看：

Benchmarks：各项能力评分
Pricing：输入和输出价格
Context Length：支持的上下文长度

注意：不同排行榜的评估方式可能不同。例如，一些排行榜更强调编程 benchmark，而忽略了多模态能力或长上下文能力。因此排名只能作为参考。

以及存在一个问题，你不能因为模型能力而忽视了价格，到时候看看账单人傻了

综合表现优秀的模型推荐：

模型	特点
GPT-5系列	综合能力强，适合各种场景
Claude 4 Sonnet系列	长上下文能力强，适合处理长文本
qwen/qwen3-coder	编程能力强，免费额度充足
DeepSeek V3 / V3.2	综合能力强，性价比好
Gemini 3 Flash系列	速度快，价格便宜
Gemini 系列	综合能力强，多模态任务表现优秀

编程模型推荐

如果你主要用 OpenClaw 来辅助编程，以下是各模型的表现：

能力最强的编程模型：

Claude Opus（包括 Claude 4 Opus系列）在编程任务中通常表现非常优秀
但有以下限制：
- 价格较高
- 国内访问可能不稳定
- 中文优化不如国内模型

如果你感兴趣，可以查看 OpenClaw 官方 Anthropic 配置文档。

对国内用户更实用的选择：

模型	特点
MiniMax M2.5	中文理解好，性价比高
qwen/qwen3-coder	阿里云编程专用模型，免费额度充足
DeepSeek V3 / V3.2	综合能力强，性价比好

DeepSeek V3 / V3.2 是目前 DeepSeek 系列的主力模型，综合能力优秀。

总结：如果你的网络条件允许且预算充足，Claude Opus 是最强的选择。否则，MiniMax M2.5、qwen/qwen3-coder 或 DeepSeek V3/V3.2 是更实用的方案。

Google Gemini 系列在综合能力和多模态任务方面也非常强。例如 Gemini 生态中的 Nano Banana 图像模型，在图形生成和视觉内容创作领域表现非常优秀。如果你的需求涉及图像生成或多模态理解，可以考虑 Gemini 系列。

提示：新手推荐从 MiniMax 或 Qwen 开始，配好 5 分钟就能用上。

4. Windows 安装步骤

新手快速安装（推荐）

如果你只是想快速体验 OpenClaw，可以直接使用官方提供的快速安装方式。两步就能搞定！

步骤 1：安装 OpenClaw

npm install -g openclaw@latest

步骤 2：运行新手引导

openclaw onboard --install-daemon

这个命令会自动完成以下操作：

初始化 OpenClaw 配置
安装 Gateway 服务
创建默认配置文件
启动 OpenClaw 服务

是的，你没看错，只需要这两条命令，就可以完成基础安装！

安装完成后，你可以：

运行交互式对话：openclaw
打开 Web 界面：openclaw dashboard
配置模型：按第 5 章的说明，给 OpenClaw 配上你喜欢的模型

官方文档：如果你想了解更多详细内容，可以参考 OpenClaw 官方中文文档，特别是其中的 快速开始（Quick Start） 部分。

如果你想了解 OpenClaw 的完整安装过程和每一步的作用，可以继续阅读下面的进阶安装教程。

下面正式开始安装，按顺序来就行。

4.1 准备环境

你需要先装好 Node.js（推荐 LTS 版本，22 及以上）。

安装 Node.js

方法一：直接安装

访问 Node.js 官网
下载 Windows Installer (.msi)
一路 Next 就行
如果出现了网络问题之类的，参考我的另一篇文章的教程内容 node.js的详细安装步骤。

方法二：nvm（推荐，方便管理多版本）

# 安装 nvm for Windows
# 访问 https://github.com/coreybutler/nvm-windows/releases 下载

# 安装后，在 PowerShell 中运行：
nvm install 22
nvm use 22

验证一下：

node -v
# 应该显示 v22.x.x

npm -v
# 应该显示 8.x.x

切换 npm 镜像（国内用户建议）

npm config set registry https://registry.npmmirror.com

安装 Git（可选但建议）

有些技能依赖 Git，建议安装一个：

访问 Git 官网
如果有配置问题，可以参考我这篇文章的内容 Git配置
下载安装，一路 Next

4.2 修改执行策略

Windows 默认不让跑脚本，得先改一下设置。以管理员身份打开 PowerShell，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

输入 Y 确认。

4.3 运行安装脚本

现在可以装 OpenClaw 了。在 PowerShell 中执行：

iwr -useb https://openclaw.ai/install.ps1 | iex

等一会儿，脚本会自动：

检测 Node.js 环境
下载安装 OpenClaw
配置路径

出现 「OpenClaw installed successfully」 就说明装好了。

4.4 初始化向导

第一次运行会进入向导：

openclaw onboard

流程大概是这样的：

风险提示 → 输入 yes
配置模式 → 选择 QuickStart
模型选择 → 先跳过，后面手动配
渠道选择 → 先跳过
技能包 → 选择 No

4.5 验证安装

装好了可以验证一下：

# 查看版本
openclaw --version

# 检查状态
openclaw status

# 体检
openclaw doctor

# 打开 Web 面板
openclaw dashboard

openclaw dashboard 会启动一个本地网页，默认 http://localhost:8080，可以在浏览器里可视化配置。

5. 配置 AI 模型

装好了不代表能用，你得给它接个模型。下面分别说几种主流方案。

官方文档：如果你想了解更多配置细节，可以参考 OpenClaw 官方中文文档，里面有更详细的 provider 配置指南和故障排查说明。

5.1 配置前必看：API 概念解释

在配置模型之前，先解释几个关键概念：

概念	说明	示例
Provider（服务商）	提供 AI 模型服务的公司或平台	MiniMax、阿里云、OpenRouter
Base URL	API 服务器的地址	`https://api.minimaxi.com/v1`
API Key	访问 API 的密钥，相当于”密码”	`sk-xxxxxx`
Model ID	具体模型的名字	`MiniMax-M2.5`、`qwen-plus`
Config JSON	配置信息的 JSON 格式	包含上述字段的结构化配置

为什么要配置这些？

OpenClaw 需要知道：

去哪里找模型（Base URL）
用什么凭证访问（API Key）
使用哪个具体模型（Model ID）

配置方式总览

配置模型有三种方式：

方式	难度	适用人群
方法一：CLI 命令	中等	熟悉命令行的用户
方法二：修改配置文件	较难	需要批量配置的用户
方法三：Web 页面配置（推荐）	简单	新手用户

如果你不熟悉命令行，推荐使用 Web 页面配置（方法三），可视化界面更容易上手。内容在5.8下面可以细节查阅。

5.2 配置 MiniMax

MiniMax 的 M2.5 挺好用的，性价比高。

获取 API Key

访问 MiniMax 开放平台
注册账号 → 实名认证
进入「API Keys」→ 创建 Key
复制保存，只看一次

配置命令

# 配置 MiniMax
openclaw config set 'models.providers.minimax' --json '{
  "baseUrl": "https://api.minimaxi.com/v1",
  "apiKey": "你的MiniMax_API_Key",
  "api": "openai-completions",
  "models": [
    { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" },
    { "id": "MiniMax-M2.5-highspeed", "name": "MiniMax M2.5 高速版" }
  ]
}'

# 设为默认模型
openclaw models set minimax/MiniMax-M2.5

更安全的做法：环境变量

把 Key 存环境变量里，避免写在配置里：

# 临时设置（当前终端有效）
$env.MINIMAX_API_KEY = "你的Key"

# 或者永久设置
[System.Environment]::SetEnvironmentVariable("MINIMAX_API_KEY", "你的Key", "User")

配置时用 $MINIMAX_API_KEY 代替实际 Key。

MiniMax Coding Plan（推荐编程用户）

如果你主要用于编程，MiniMax 提供了专门的 Coding Plan，性价比更高。

获取 API Key 并开通 Coding Plan：

访问 MiniMax 开放平台
注册账号 → 实名认证
进入「API Keys」→ 创建 Key
进入「Coding Plan」页面，开通 Coding Plan
复制保存 API Key

配置命令：

# 配置 MiniMax Coding Plan
openclaw config set 'models.providers.minimax' --json '{
  "baseUrl": "https://api.minimaxi.com/v1",
  "apiKey": "你的MiniMax_API_Key",
  "api": "openai-completions",
  "models": [
    { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" },
    { "id": "MiniMax-M2.5-highspeed", "name": "MiniMax M2.5 高速版" }
  ]
}'

# 设为默认模型
openclaw models set minimax/MiniMax-M2.5

提示：Coding Plan 通常有更低的调用价格，适合高频使用的用户。

5.3 配置阿里云 Model Studio

阿里云 Model Studio 是阿里云提供的大模型服务平台，通过它可以使用 Qwen 等模型。除了标准版，还有专门的 Coding Plan 适合编程用户。

获取 API Key

访问阿里云 Model Studio
注册账号 → 实名认证
进入「API Keys」→ 创建 Key
复制保存

开通 Coding Plan（推荐编程用户）

访问阿里云百炼
进入「Coding Plan」页面
开通 Coding Plan
获取专门的 Coding Plan API Key

配置命令

标准版：

# 配置阿里云 Model Studio
openclaw config set 'models.providers.qwen' --json '{
  "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "apiKey": "你的阿里云API_Key",
  "models": [
    { "id": "qwen/qwen3-coder", "name": "Qwen Coder Model" },
    { "id": "qwen-portal/vision-model", "name": "Qwen Vision Model" },
    { "id": "qwen-plus", "name": "Qwen Plus" },
    { "id": "qwen-max", "name": "Qwen Max" }
  ]
}'

# 设为默认
openclaw models set qwen/qwen/qwen3-coder

Coding Plan 版（如果用的是阿里云 Coding Plan）：

openclaw config set 'models.providers.qwen' --json '{
  "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
  "apiKey": "你的Coding_Plan_Key",
  "models": [
    { "id": "qwen3-max-2026-01-23", "name": "Qwen3 Max" },
    { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" }
  ]
}'

提示：Coding Plan 通常有更低的调用价格或免费额度，适合高频编程的用户。

5.4 配置 OpenRouter

OpenRouter 是一个聚合了上百种 AI 模型的平台，通过它可以用一个 API Key 访问 GPT、Claude、DeepSeek 等多种模型。

获取 API Key

访问 OpenRouter 官网
注册账号
进入「API Keys」→ 创建 Key
复制保存，只看一次

配置命令

openclaw config set 'models.providers.openrouter' --json '{
  "baseUrl": "https://openrouter.ai/api/v1",
  "apiKey": "你的OpenRouter_API_Key",
  "models": [
    { "id": "openai/gpt-5", "name": "GPT-5" },
    { "id": "anthropic/claude-4-sonnet", "name": "Claude 4 Sonnet" },
    { "id": "deepseek/deepseek-v3", "name": "DeepSeek V3" },
    { "id": "google/gemini-3-flash", "name": "Gemini 3 Flash" }
  ]
}'

# 设为默认
openclaw models set openrouter/openai/gpt-5

注意：OpenRouter 上的模型 ID 格式和直接调用时不太一样，格式是 提供商/模型名，如 openai/gpt-5、anthropic/claude-4-sonnet。

参考：你可以访问 OpenRouter 排行榜查看各模型的评分和价格排名，作为选择参考。

5.5 配置 SiliconFlow

SiliconFlow（硅基流动）是国内的一个 AI 模型聚合平台，提供多种模型接口，对国内用户比较友好。

特点

国内访问速度快：服务器在国内，延迟低
模型种类多：支持 Qwen、DeepSeek、Llama 等多种模型
价格实惠：按量计费，有免费额度

配置参考

详细配置教程请参考官方文档：

SiliconFlow 官方配置指南

基本步骤：

访问 SiliconFlow 官网注册账号
获取 API Key
参考官方文档配置 provider

5.6 配置 OpenAI

如果你有 OpenAI 的 API Key，可以直接配置。

获取 API Key

访问 OpenAI 平台
进入「API Keys」→ 创建 Key
复制保存

注意：国内用户可能需要科学上网才能访问 OpenAI。

配置命令

openclaw config set 'models.providers.openai' --json '{
  "apiKey": "你的OpenAI_API_Key",
  "models": [
    { "id": "gpt-5", "name": "OpenAI GPT-5" },
    { "id": "gpt-4o", "name": "GPT-4o" },
    { "id": "gpt-4o-mini", "name": "GPT-4o Mini" }
  ]
}'

# 设为默认
openclaw models set openai/gpt-5

5.7 配置 Qwen OAuth（推荐）

Qwen OAuth 是最推荐的配置方式，因为它有免费额度，而且不需要手动获取 API Key，直接用阿里云账号授权就行。

配置步骤

运行配置向导：
```
openclaw onboard
```
选择模型服务商时，选择 Qwen
选择 Qwen OAuth
会弹出一个浏览器窗口，让你用阿里云账号登录授权
授权成功后，选择想用的模型：
- qwen/qwen3-coder：编程专用
- qwen-portal/vision-model：视觉理解

手动配置（如果向导失败）

# 运行 OAuth 授权
openclaw config set oauth qwen

这会打开浏览器让你完成授权流程。授权完成后，配置会自动保存。

5.8 配置 Ollama 本地模型

如果你有显卡，想在本地跑模型（零 API 费用），可以使用 Ollama。

重要概念：Ollama 负责在本地运行模型，而 OpenClaw 需要通过 Gateway 来连接 Ollama。

5.8.1 安装 Ollama

访问 Ollama 官网
下载 Windows 版本
运行安装包，自动启动

如果访问 Ollama 官网异常，可以尝试以下国内镜像源：

https://www.newbe.pro/Mirrors/Mirrors-ollama

https://ollama.ruanmao.net/

Ollama 默认监听 http://localhost:11434。

中国用户推荐：如果你在中国大陆使用，下载模型时可能会遇到速度慢或连接不稳定的问题。建议配置国内镜像源（见下文），可以大幅提升下载速度。

配置国内镜像源（可选，中国用户推荐）

国内镜像源列表：

镜像站	地址
魔搭社区	https://ollama.modelscope.cn
DeepSeek	https://ollama.deepseek.com
浙江大学	https://ollama.zju.edu.cn
国内整理站	https://www.newbe.pro/Mirrors/Mirrors-ollama

配置方法（Windows）：

# 临时生效
set OLLAMA_HOST=https://ollama.modelscope.cn

# 永久生效
setx OLLAMA_HOST https://ollama.modelscope.cn

Linux / macOS：

export OLLAMA_HOST=https://ollama.modelscope.cn

配置完成后，可以使用 ollama pull qwen3 等命令下载模型。如果下载成功，说明镜像源已生效。

小提示：如果某个镜像下载失败，可以尝试更换其他镜像源。

5.8.2 下载模型

显存说明：模型越大，需要的显存越多。3B 模型约需 4-6GB 显存，8B 模型约需 8-12GB 显存。根据你的显卡选择合适的模型。

根据你的电脑配置选择：

电脑配置	推荐模型
入门级（无独显或显存 < 4GB）	phi3:mini、qwen2.5:1.8b
主流配置（4-6GB 显存）	qwen2.5:3b、qwen2.5-coder:3b、qwen3:4b
中高端配置（8GB+ 显存）	qwen3:8b、qwen3:14b

提示：如果 Ollama 尚未支持 Qwen3，Qwen2.5 仍然是很好的替代选择。

# 查看有哪些模型
ollama list

# 入门级模型（CPU 也能跑）
ollama pull phi3:mini

# 主流配置 - 对话模型（推荐）
ollama pull qwen2.5:3b

# 主流配置 - 编程模型
ollama pull qwen2.5-coder:3b

# 中高端配置 - 更强能力
ollama pull qwen3:8b

提示：如果显存不够，Ollama 会自动使用量化版本，或者你可以手动拉取量化版本，如 qwen2.5:3b-q4_K_M，占用更少显存。

5.8.3 配置 OpenClaw 连接 Ollama

配置 OpenClaw 通过 Gateway 连接本地 Ollama：

openclaw config set 'models.providers.ollama' --json '{
  "baseUrl": "http://localhost:18789/v1",
  "apiKey": "ollama-local",
  "models": [
    { "id": "qwen2.5:3b", "name": "Qwen 2.5 3B" },
    { "id": "qwen2.5-coder:3b", "name": "Qwen 2.5 Coder 3B" },
    { "id": "qwen3:8b", "name": "Qwen 3 8B" },
    { "id": "phi3:mini", "name": "Phi-3 Mini" }
  ]
}'

# 设为默认（推荐 3B 模型，8GB+ 显存可用 qwen3:8b）
openclaw models set ollama/qwen2.5:3b

注意：这里 Gateway 的地址是 http://localhost:18789（你启动 Gateway 时指定的端口），而不是直接连接 Ollama 的 11434 端口。这样 OpenClaw 可以统一管理所有模型连接。

5.8.4 什么是 Gateway？

Gateway（网关）是 OpenClaw 的后台服务，你可以把它理解成一个”翻译官”——OpenClaw 通过它和各类模型对话。

简单来说：

Gateway 负责统一管理各种模型的连接
Gateway 负责处理身份验证
Gateway 负责转发请求到不同的模型供应商

工作架构图：

你
   ↓
OpenClaw CLI（你输入命令的地方）
   ↓
Gateway（网关，负责连接管理）
   ↓
模型供应商
(MiniMax / Qwen / OpenRouter / Ollama)

为什么需要 Gateway？ OpenClaw 通过 Gateway 这个统一的入口，可以方便地连接各种不同的模型供应商，不需要为每个模型单独配置连接方式。

5.8.5 安装 Gateway

OpenClaw 安装时通常会自动包含 Gateway。如果需要单独安装：

npm install -g @openclaw/gateway

5.8.6 启动 Gateway

Gateway 是 OpenClaw 的核心运行进程，负责：

管理模型连接
提供 HTTP / WebSocket API
提供 Web 控制界面

启动 Gateway（推荐）

最简单的方式是运行：

openclaw gateway run

这个命令会启动 Gateway 服务。启动后，默认是：

http监听地址://127.0.0.1:18789

你可以在浏览器中打开这个地址，访问 Web 控制界面来配置模型。

常用参数

如果需要自定义，可以使用以下参数：

参数	作用	示例
`--port`	指定端口号	`--port 8080`
`--verbose`	显示详细日志，方便排查问题	`--verbose`
`--force`	强制占用端口	`--force`

示例：

# 指定端口启动
openclaw gateway run --port 8080

# 显示详细日志
openclaw gateway run --verbose

# 端口冲突时强制占用
openclaw gateway run --force

5.8.7 高级配置（可选）

如果你想进一步自定义 Gateway：

选项	说明
`--hot-reload`	启用热重载，修改配置无需重启
`SIGUSR1`	发送信号重启 Gateway（Linux/macOS）
`--config`	指定配置文件路径

示例：

# 热重载模式
openclaw gateway --port 18789 --hot-reload

方法一：CLI 命令配置

使用 openclaw config set 命令直接配置模型参数。

# 语法
openclaw config set 'models.提供者名称' --json '{
  "baseUrl": "https://api.example.com/v1",
  "apiKey": "你的API_Key",
  "models": [
    { "id": "模型ID", "name": "显示名称" }
  ]
}'

示例（配置 MiniMax）：

openclaw config set 'models.providers.minimax' --json '{
  "baseUrl": "https://api.minimaxi.com/v1",
  "apiKey": "你的MiniMax_API_Key",
  "api": "openai-completions",
  "models": [
    { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" }
  ]
}'

优点：快速、适合自动化脚本缺点：需要记忆命令语法

方法二：修改配置文件

直接编辑 OpenClaw 的配置文件 claude.json。

配置文件位置：

Windows: %USERPROFILE%\.openclaw\claude.json
macOS/Linux: ~/.openclaw/claude.json

示例配置：

{
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/v1",
        "apiKey": "你的MiniMax_API_Key",
        "api": "openai-completions",
        "models": [
          { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" }
        ]
      }
    }
  }
}

优点：可批量配置、易于备份缺点：需要手动编辑 JSON 格式

方法三：通过 Web 页面配置（推荐新手）

除了命令行和配置文件，你还可以通过 Web 界面 来配置模型。这种方式更直观，适合新手用户。

第一步：启动 Gateway

Gateway 不仅提供 API 服务，还自带 Web 控制界面。在终端运行：

openclaw gateway run

这个命令会启动 Gateway 服务，并在后台运行。

第二步：打开浏览器访问

Gateway 的 Web 界面默认地址是：

http://127.0.0.1:18789

在浏览器中打开这个地址，你会看到 Gateway 的管理界面。

第三步：进入配置页面

在界面中找到并点击：

Config → Models

这里可以管理所有的模型配置。

第四步：添加 Provider 配置

以添加 MiniMax 为例：

点击 Add Provider 或类似按钮
选择或填写 Provider 类型
填写以下信息：

字段	值
Base URL	`https://api.minimaxi.com/v1`
API Key	你的 MiniMax API Key

打开 Auth Header 选项（如果需要）
填写 API Key

第五步：保存配置

点击 Save 或 Update 按钮保存配置。

提示：保存后，Gateway 会自动刷新配置，你可能需要重启 OpenClaw 才能生效。

这种方式的好处是：

可视化操作，不需要记命令
实时看到配置状态
适合不熟悉命令行的用户

6. 使用 cc-switch 管理 API（推荐）

如果你配置了多个模型 provider，每次手动改配置会比较麻烦。cc-switch 是一个跨平台桌面工具，可以帮你一键切换不同的 AI API 配置，支持 Claude Code、OpenClaw、Gemini 等。

6.1 为什么用 cc-switch？

手动管理 API Key 的问题：

每个 provider 都要单独配置环境变量
切换模型需要修改 JSON 配置
多个账号/供应商时容易混乱

cc-switch 的优势：

可视化界面，不用改命令行配置
一键切换 provider
支持 MCP 服务器管理
支持 Skills/Prompts 预设

6.2 cc-switch 的工作原理

重要：cc-switch 会把当前启用的 provider 配置信息写入环境变量。OpenClaw 启动时会自动读取这些环境变量，因此你不需要手动编辑 OpenClaw 的配置文件。

这就是 cc-switch 的便捷之处：你只需要在 cc-switch 中切换 provider，然后启动 OpenClaw，它就会自动使用当前配置。

6.3 安装 cc-switch

Windows：

访问 cc-switch GitHub Releases
下载 CC-Switch-v{version}-Windows.msi 或便携版
运行安装

macOS：

brew tap farion1231/ccswitch
brew install --cask cc-switch

Linux：

支持 .deb、.rpm、.AppImage 等多种格式。

6.4 添加 Provider

启动 cc-switch
点击右上角 「+」 或「Add Provider」
选择预设的 provider（MiniMax、Qwen 等）
填写你的 API Key
点击「添加」

6.5 切换 Provider

在主界面选择你想用的 provider
点击「启用」
重启 OpenClaw（如果正在运行）

6.6 OpenClaw 自动使用当前配置

cc-switch 会把当前启用的 provider 配置写入环境变量。OpenClaw 启动时会自动读取这些环境变量，所以你只需要：

# 切换 provider 后，重启 OpenClaw
openclaw restart
# 或者
openclaw serve

OpenClaw 会自动使用 cc-switch 中当前启用的 API 配置。

7. 启动和使用

配好模型后，就可以用了。

# 交互式对话
openclaw

# 启动 Web 服务
openclaw serve --port 3000

# 启动 Gateway（如未自动启动）
openclaw gateway run

# Web 面板
openclaw dashboard

直接输入文字就能对话。如果配好了工具，它还能帮你操作文件、搜东西之类的。

8. 推荐配置

根据不同场景，给个参考：

场景	推荐模型	理由
编程	qwen/qwen3-coder	专为编程优化，GitHub 集成好
视觉理解	qwen-portal/vision-model	支持图像理解
日常对话	MiniMax-M2.5	中文理解好，性价比高
深度推理	Qwen3-Max	能力强
本地离线	Ollama qwen2.5:3b	主流配置可用，完全免费

我的常用搭配：日常用 MiniMax，编程切到 qwen/qwen3-coder。

切换模型很方便：

# 切到 MiniMax
openclaw models set minimax/MiniMax-M2.5

# 切到 Qwen 编程
openclaw models set qwen/qwen/qwen3-coder

# 切到 Qwen 视觉
openclaw models set qwen/qwen-portal/vision-model

9. 常见问题

命令找不到

# 检查是否装上了
npm list -g openclaw

# 重启 PowerShell 再试

# 不行就重装
npm install -g openclaw@latest

API Key 报错

检查 Key 对不对，有没有多余空格
看看还有没有余额
建议用环境变量方式配置

Ollama 连不上

# 确认 Ollama 启动了
ollama list

# 试试能不能访问
curl http://localhost:11434

Gateway 连不上

# 确认 Gateway 启动了
openclaw gateway run

# 如果端口被占用，加 --force 强制启动
openclaw gateway run --force

# 或者指定其他端口
openclaw gateway run --port 8080

响应太慢

远程 API：检查网络，或者换个模型
Ollama：考虑用更小的模型，如 qwen2.5:3b 或量化版本 qwen2.5:3b-q4_K_M

安装脚本报错

确认执行策略改过了：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

10. 替代方案：腾讯工作流 AI（WorkBuddy）

如果你觉得 OpenClaw 部署太复杂，不妨考虑一下 腾讯工作流 AI（又称 WorkBuddy ）。

什么是 WorkBuddy？

WorkBuddy 是腾讯推出的 AI 编程助手，类似于 Cursor、Windsurf 的产品。它不需要本地部署，直接通过 VS Code 或 JetBrains 插件即可使用。

特点

无需部署：安装插件即可使用
免费额度充足：腾讯提供免费使用额度
中文优化好：对中文开发者友好
集成腾讯生态：可接入微信、腾讯云等服务

适用人群

编程新手，不想折腾环境配置
追求开箱即用的体验
只想简单体验 AI 编程辅助

与 OpenClaw 的对比

特性	OpenClaw	WorkBuddy
部署方式	本地部署	无需部署
定制性	高	中
学习成本	较高	低
费用	免费/付费	有免费额度

总结：如果你只是想体验 AI 编程辅助，WorkBuddy 是个更简单的选择。如果你想要更高的定制性和可扩展性，OpenClaw 仍然是更好的选择。

结语

这篇教程可能还是不够详细，但是我已经写入了很基础的详细配置教程，后续我会更新大模型参数详解之类的教程，后续我可能会更新openclaw接入飞书的详细教程等。

OpenClaw Windows Installation & Configuration Guide (MiniMax / Qwen / Ollama)

Tue, 10 Mar 2026 00:00:00 GMT

Introduction

I’ve been thinking about whether to make an OpenClaw deployment tutorial, because the OpenClaw Chinese documentation is already quite detailed. However, I realized that many people might not know that Chinese documentation exists, or still find it confusing even when following the tutorial. Recently, OpenClaw has become extremely popular in China—it’s almost overhyped, like a modern-day “qigong fever.” But I still think it’s worth making a detailed tutorial so you can try deploying it yourself. After all, you won’t know if a product is right for you until you’ve tried it. The idea of having your own Jarvis-like personal AI assistant is quite appealing.

1. What is OpenClaw?

Let me give you a quick overview. OpenClaw (formerly known as Clawdbot—pretty interesting name change, right?) is an open-source AI Agent framework. Simply put, you can think of it as an “AI operating system”—it doesn’t provide AI capabilities itself, but it helps you connect to various large language models to accomplish tasks.

Unlike regular chatbots, OpenClaw can do much more:

Operate on file systems
Execute commands
Write and debug code
Search for information
Integrate with communication tools like Feishu and Telegram

You just need to pair it with the right model, and it can help you get things done.

2. How OpenClaw Works

Let’s clarify an important concept: OpenClaw is just a “shell”—you need to provide your own model.

The workflow looks like this:

You (input) → OpenClaw → AI Model → Return result

You can choose to connect to:

Cloud Models: MiniMax, Qwen (Alibaba Cloud Bailian), OpenAI, Claude, and more
Local Models: Models running locally via Ollama

Each approach has its pros and cons, which I’ll explain in detail later.

Tip: This guide includes a dedicated section on configuring Ollama local models—see Section 5.8.

3. Deployment Options and Model Choices

Official Documentation: For more advanced configuration options, check out the OpenClaw English Documentation.

Before we start installing, let’s understand the two deployment options and how to choose a model.

3.1 Deployment Options Explained

OpenClaw has two deployment options:

Deployment	Description	Best For
Local Deployment	Run on your own Windows PC	Personal use, privacy-first, low cost
Remote Server	Run on a cloud server (e.g., Linux server)	Multi-user sharing, 24/7 operation

This guide focuses on local deployment—running OpenClaw on your own Windows PC. While remote server deployment is convenient (vendors handle everything for you), you might actually want your own personal Jarvis on your private computer. While this comes with more risks, you’ll weigh and accept them yourself.

3.2 Which Model Should You Choose?

Before starting installation, decide which model option you’ll use. This affects the configuration steps.

Cloud APIs (Recommended for Beginners)

Call cloud model APIs with pay-as-you-go pricing (most have free tiers).

Provider	Recommended Model	Features
MiniMax	M2.5	Great cost-performance, well-optimized for Chinese
Qwen	qwen/qwen3-coder / qwen/qwen3-vl	Strong coding abilities, generous free tier from Alibaba Cloud

qwen3-coder is a coding-optimized model released by Alibaba. | OpenAI | GPT-5 series | Strong all-around capabilities |

Pros: No GPU needed, fast responses, reliable capabilities Cons: Requires payment (but usually has free credits)

Local Models (Ollama)

Run models on your own computer, completely free, but requires specific hardware.

Pros: Zero cost, better privacy Cons: Requires a capable GPU, response speed depends on hardware

Honestly, most computers can’t really handle this. You can check your GPU configuration. Even the workstation in our lab didn’t go with the Ollama solution—the main issue isn’t just VRAM being enough to run, you also can’t ignore speed. Plus, my setup is already pretty powerful, but I still didn’t choose Ollama. The API solution is pretty good—you just pay a little.

My Suggestion: Beginners should just use a remote API—MiniMax or Qwen works great. Once configured, you can start using it in 5 minutes.

3.3 How to Choose the Right LLM

Choosing an LLM mainly depends on these factors:

Factor	Description
Price	Cloud APIs charge per usage; different models vary greatly in price
Speed	Response speed depends on model size and network
Context Length	How much text it can process; longer = more expensive
Coding Ability	Some models are specifically optimized for programming
Reasoning Ability	Ability to solve complex problems

Using the OpenRouter Rankings

OpenRouter provides a convenient Model Rankings page where you can filter by:

Performance: Overall benchmark scores
Price: Sorting by input/output prices
Context Length: Maximum supported tokens
Latency: Response speed

When searching for a specific model on OpenRouter, you can view:

Benchmarks: Capability scores in various areas
Pricing: Input and output prices
Context Length: Supported context length

Note: Different ranking systems may use different evaluation methods. For example, some rankings emphasize coding benchmarks while ignoring multimodal capabilities or long context abilities. Rankings should only be used as a reference.

Also, there’s the issue—you can’t ignore pricing just because of model capability. Check your bill later and you’ll be shocked!

Recommended Models with Excellent Overall Performance:

Model	Features
GPT-5 series	Strong all-around, suitable for various scenarios
Claude 4 Sonnet series	Strong long context, great for handling long texts
qwen/qwen3-coder	Strong coding ability, generous free tier
DeepSeek V3 / V3.2	Strong overall capability, great cost-performance
Gemini 3 Flash series	Fast speed, affordable price
Gemini series	Strong all-around, excellent at multimodal tasks

Coding Model Recommendations

If you’re mainly using OpenClaw for programming assistance, here’s how each model performs:

Most capable coding models:

Claude Opus (including Claude 4 Opus series) usually performs exceptionally well on coding tasks
However, there are limitations:
- Higher price
- May be unstable to access in China
- Not as well-optimized for Chinese as domestic models

If you’re interested, check out the OpenClaw Official Anthropic Configuration Documentation.

More practical choices for Chinese users:

Model	Features
MiniMax M2.5	Good Chinese understanding, great cost-performance
qwen/qwen3-coder	Alibaba’s coding-specific model, generous free tier
DeepSeek V3 / V3.2	Strong overall capability, great cost-performance

DeepSeek V3 / V3.2 is the current flagship model in the DeepSeek series with excellent overall capabilities.

Summary: If your network conditions allow and budget is sufficient, Claude Opus is the strongest choice. Otherwise, MiniMax M2.5, qwen/qwen3-coder, or DeepSeek V3/V3.2 are more practical options.

Google Gemini series is also very strong in overall capabilities and multimodal tasks. For example, Nano Banana in the Gemini ecosystem performs exceptionally well in image generation and visual content creation. If your needs involve image generation or multimodal understanding, consider the Gemini series.

Tip: Beginners are recommended to start with MiniMax or Qwen—once configured, you can use it in 5 minutes.

4. Windows Installation Steps

Quick Installation (Recommended)

If you just want to try OpenClaw quickly, you can use the official quick install method. Only two steps!

Step 1: Install OpenClaw

npm install -g openclaw@latest

Step 2: Run the Setup Wizard

openclaw onboard --install-daemon

This command will automatically:

Initialize OpenClaw configuration
Install the Gateway service
Create default config files
Start the OpenClaw service

Yes, you read that right—just these two commands complete the basic installation!

After installation, you can:

Run interactive chat: openclaw
Open the web interface: openclaw dashboard
Configure models: Follow Chapter 5 to configure your preferred models for OpenClaw

Official Documentation: For more details, check out the OpenClaw Official Documentation, especially the Quick Start section.

If you want to understand the complete OpenClaw installation process and what each step does, continue reading the advanced installation tutorial below.

Now let’s start the installation. Just follow the steps in order.

4.1 Environment Preparation

You need to have Node.js installed first (LTS version recommended, 22 or higher).

Installing Node.js

Method 1: Direct Installation

Visit Node.js Official Website
Download Windows Installer (.msi)
Click Next through the wizard
If you encounter network issues, refer to my other article: Node.js detailed installation steps.

Method 2: nvm (Recommended for managing multiple versions)

# Install nvm for Windows
# Visit https://github.com/coreybutler/nvm-windows/releases to download

# After installation, run in PowerShell:
nvm install 22
nvm use 22

Verify:

node -v
# Should show v22.x.x

npm -v
# Should show 8.x.x

Switch npm Registry (Recommended for China Users)

npm config set registry https://registry.npmmirror.com

Install Git (Optional but Recommended)

Some skills depend on Git—it’s recommended to install:

Visit Git Official Website
For configuration issues, refer to my article: Git Configuration
Download and install, click Next through the wizard

4.2 Modify Execution Policy

Windows doesn’t allow running scripts by default—you need to change this setting. Open PowerShell as Administrator and run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Type Y to confirm.

4.3 Run the Installation Script

Now you can install OpenClaw. Execute in PowerShell:

iwr -useb https://openclaw.ai/install.ps1 | iex

Wait a moment—the script will automatically:

Detect Node.js environment
Download and install OpenClaw
Configure PATH

When you see “OpenClaw installed successfully”, it’s done.

4.4 Setup Wizard

The first run will enter the wizard:

openclaw onboard

The process goes like this:

Risk warning → Type yes
Configuration mode → Select QuickStart
Model selection → Skip for now, configure manually later
Channel selection → Skip for now
Skills package → Select No

4.5 Verify Installation

You can verify the installation:

# Check version
openclaw --version

# Check status
openclaw status

# Run diagnostics
openclaw doctor

# Open web panel
openclaw dashboard

openclaw dashboard will start a local web page, default at http://localhost:8080. You can visually configure it in your browser.

5. Configuring AI Models

Just installing doesn’t mean it’s ready to use—you need to connect it to a model. Below are instructions for several popular options.

Official Documentation: For more configuration details, check out the OpenClaw Official Documentation, which has more detailed provider configuration guides and troubleshooting tips.

5.1 Must-Read Before Configuration: API Concept Explanation

Before configuring models, let me explain some key concepts:

Concept	Description	Example
Provider	Company or platform providing AI model services	MiniMax, Alibaba Cloud, OpenRouter
Base URL	Address of the API server	`https://api.minimaxi.com/v1`
API Key	Key to access the API, like a “password”	`sk-xxxxxx`
Model ID	Name of the specific model	`MiniMax-M2.5`, `qwen-plus`
Config JSON	JSON format for configuration info	Structured config containing the above fields

Why do you need to configure these?

OpenClaw needs to know:

Where to find the model (Base URL)
What credentials to use (API Key)
Which specific model to use (Model ID)

Recommended: Using cc-switch to Manage Multiple Providers

If you plan to configure multiple model providers, it’s recommended to use cc-switch to manage them:

Multi-Provider Management: One interface to manage all API configurations
One-click Switching: Switch between different models anytime without manually changing config
Auto Environment Variables: OpenClaw automatically reads environment variables set by cc-switch

Tip: See Chapter 6 for a detailed introduction to cc-switch. If you don’t want manual configuration, you can skip this chapter’s provider configuration and directly read the cc-switch section.

Configuration Method Overview

There are three ways to configure models:

Method	Difficulty	Best For
Method 1: CLI Commands	Medium	Users familiar with command line
Method 2: Edit Config File	Harder	Users needing batch configuration
Method 3: Web Page Config (Recommended)	Easy	Beginner users

If you’re not familiar with the command line, Web Page Configuration (Method 3) is recommended—visual interface is easier to get started. See details below in section 5.8.

5.2 Configure MiniMax

MiniMax’s M2.5 is quite good—great cost-performance.

Get API Key

Visit MiniMax Open Platform
Register → Real-name authentication
Go to “API Keys” → Create Key
Copy and save—you can only see it once

Configuration Command

# Configure MiniMax
openclaw config set 'models.providers.minimax' --json '{
  "baseUrl": "https://api.minimaxi.com/v1",
  "apiKey": "your_MiniMax_API_Key",
  "api": "openai-completions",
  "models": [
    { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" },
    { "id": "MiniMax-M2.5-highspeed", "name": "MiniMax M2.5 High Speed" }
  ]
}'

# Set as default model
openclaw models set minimax/MiniMax-M2.5

Safer Approach: Environment Variables

Store the key in environment variables instead of writing it in config:

# Temporary (only valid for current terminal)
$env.MINIMAX_API_KEY = "your_Key"

# Or permanent
[System.Environment]::SetEnvironmentVariable("MINIMAX_API_KEY", "your_Key", "User")

When configuring, use $MINIMAX_API_KEY instead of the actual key.

MiniMax Coding Plan (Recommended for Programmers)

If you mainly use it for programming, MiniMax offers a dedicated Coding Plan with better cost-performance.

Get API Key and Activate Coding Plan:

Visit MiniMax Open Platform
Register → Real-name authentication
Go to “API Keys” → Create Key
Go to “Coding Plan” page, activate Coding Plan
Copy and save the API Key

Configuration Command:

# Configure MiniMax Coding Plan
openclaw config set 'models.providers.minimax' --json '{
  "baseUrl": "https://api.minimaxi.com/v1",
  "apiKey": "your_MiniMax_API_Key",
  "api": "openai-completions",
  "models": [
    { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" },
    { "id": "MiniMax-M2.5-highspeed", "name": "MiniMax M2.5 High Speed" }
  ]
}'

# Set as default model
openclaw models set minimax/MiniMax-M2.5

Tip: Coding Plan usually has lower calling prices, suitable for high-frequency users.

5.3 Configure Alibaba Cloud Model Studio

Alibaba Cloud Model Studio is a large model service platform provided by Alibaba Cloud, which you can use to access Qwen models and more. Besides the standard version, there’s also a dedicated Coding Plan for programming users.

Get API Key

Visit Alibaba Cloud Model Studio
Register → Real-name authentication
Go to “API Keys” → Create Key
Copy and save

Activate Coding Plan (Recommended for Programmers)

Visit Alibaba Cloud Bailian
Go to “Coding Plan” page
Activate Coding Plan
Get the dedicated Coding Plan API Key

Configuration Command

Standard Version:

# Configure Alibaba Cloud Model Studio
openclaw config set 'models.providers.qwen' --json '{
  "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "apiKey": "your_Alibaba_Cloud_API_Key",
  "models": [
    { "id": "qwen/qwen3-coder", "name": "Qwen Coder Model" },
    { "id": "qwen-portal/vision-model", "name": "Qwen Vision Model" },
    { "id": "qwen-plus", "name": "Qwen Plus" },
    { "id": "qwen-max", "name": "Qwen Max" }
  ]
}'

# Set as default
openclaw models set qwen/qwen/qwen3-coder

Coding Plan Version (if using Alibaba Cloud Coding Plan):

openclaw config set 'models.providers.qwen' --json '{
  "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
  "apiKey": "your_Coding_Plan_Key",
  "models": [
    { "id": "qwen3-max-2026-01-23", "name": "Qwen3 Max" },
    { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" }
  ]
}'

Tip: Coding Plan usually has lower calling prices or free credits, suitable for high-frequency programming users.

5.4 Configure OpenRouter

OpenRouter is a platform that aggregates hundreds of AI models. Through it, you can use a single API Key to access GPT, Claude, DeepSeek, and many other models.

Get API Key

Visit OpenRouter Official Website
Register account
Go to “API Keys” → Create Key
Copy and save—you can only see it once

Configuration Command

openclaw config set 'models.providers.openrouter' --json '{
  "baseUrl": "https://openrouter.ai/api/v1",
  "apiKey": "your_OpenRouter_API_Key",
  "models": [
    { "id": "openai/gpt-5", "name": "GPT-5" },
    { "id": "anthropic/claude-4-sonnet", "name": "Claude 4 Sonnet" },
    { "id": "deepseek/deepseek-v3", "name": "DeepSeek V3" },
    { "id": "google/gemini-3-flash", "name": "Gemini 3 Flash" }
  ]
}'

# Set as default
openclaw models set openrouter/openai/gpt-5

Note: Model IDs on OpenRouter are formatted differently than direct calls—the format is provider/modelname, like openai/gpt-5, anthropic/claude-4-sonnet.

Reference: Check the OpenRouter Rankings to see model ratings and price rankings as a reference for selection.

5.5 Configure SiliconFlow

SiliconFlow is a domestic AI model aggregation platform in China, offering various model interfaces and is quite friendly for China users.

Features

Fast domestic access: Servers in China, low latency
Many model options: Supports Qwen, DeepSeek, Llama, and more
Affordable pricing: Pay-per-use with free credits

Configuration Reference

For detailed configuration tutorials, refer to the official documentation:

SiliconFlow Official Configuration Guide

Basic steps:

Visit SiliconFlow Official Website to register
Get API Key
Configure provider by referring to official docs

5.6 Configure OpenAI

If you have an OpenAI API Key, you can configure it directly.

Get API Key

Visit OpenAI Platform
Go to “API Keys” → Create Key
Copy and save

Note: China users may need to use a VPN to access OpenAI.

Configuration Command

openclaw config set 'models.providers.openai' --json '{
  "apiKey": "your_OpenAI_API_Key",
  "models": [
    { "id": "gpt-5", "name": "OpenAI GPT-5" },
    { "id": "gpt-4o", "name": "GPT-4o" },
    { "id": "gpt-4o-mini", "name": "GPT-4o Mini" }
  ]
}'

# Set as default
openclaw models set openai/gpt-5

5.7 Configure Qwen OAuth (Recommended)

Qwen OAuth is the most recommended configuration method because it has free credits and doesn’t require manually getting an API Key—just authorize with your Alibaba Cloud account.

Configuration Steps

Run the configuration wizard:
```
openclaw onboard
```
When selecting model provider, choose Qwen
Select Qwen OAuth
A browser window will pop up for you to log in with your Alibaba Cloud account for authorization
After successful authorization, select the model you want to use:
- qwen/qwen3-coder: Coding-specific
- qwen-portal/vision-model: Vision understanding

Manual Configuration (if wizard fails)

# Run OAuth authorization
openclaw config set oauth qwen

This will open a browser for you to complete the authorization process. After authorization completes, the configuration is saved automatically.

5.8 Configure Ollama Local Models

If you have a GPU and want to run models locally (zero API fees), you can use Ollama.

Important Concept: Ollama is responsible for running models locally, while OpenClaw needs to connect to Ollama through the Gateway.

5.8.1 Install Ollama

Visit Ollama Official Website
Download the Windows version
Run the installer—it will start automatically

If Ollama website is inaccessible, try these domestic mirror sources:

https://www.newbe.pro/Mirrors/Mirrors-ollama

https://ollama.ruanmao.net/

Ollama defaults to listening at http://localhost:11434.

For China Users: If you’re in Mainland China, you may encounter slow download speeds or unstable connections when downloading models. It’s recommended to configure a domestic mirror source (see below), which can significantly improve download speed.

Configure Domestic Mirror Sources (Optional, Recommended for China)

Domestic Mirror List:

Mirror Site	Address
ModelScope	https://ollama.modelscope.cn
DeepSeek	https://ollama.deepseek.com
Zhejiang University	https://ollama.zju.edu.cn
Domestic Collection	https://www.newbe.pro/Mirrors/Mirrors-ollama

Configuration method (Windows):

# Temporary effect
set OLLAMA_HOST=https://ollama.modelscope.cn

# Permanent effect
setx OLLAMA_HOST https://ollama.modelscope.cn

Linux / macOS:

export OLLAMA_HOST=https://ollama.modelscope.cn

After configuration, you can use commands like ollama pull qwen3 to download models. If download succeeds, the mirror is working.

Quick Tip: If a mirror download fails, try switching to another mirror source.

5.8.2 Download Models

VRAM Note: Larger models require more VRAM. 3B models need about 4-6GB VRAM, 8B models need about 8-12GB VRAM. Choose a suitable model based on your GPU.

Choose based on your PC configuration:

PC Configuration	Recommended Model
Entry-level (no discrete GPU or VRAM < 4GB)	phi3:mini, qwen2.5:1.8b
Mainstream (4-6GB VRAM)	qwen2.5:3b, qwen2.5-coder:3b, qwen3:4b
Mid-to-high end (8GB+ VRAM)	qwen3:8b, qwen3:14b

Tip: If Ollama doesn’t support Qwen3 yet, Qwen2.5 is still a great alternative.

# Check available models
ollama list

# Entry-level model (can run on CPU)
ollama pull phi3:mini

# Mainstream config - Chat model (recommended)
ollama pull qwen2.5:3b

# Mainstream config - Coding model
ollama pull qwen2.5-coder:3b

# Mid-to-high end - Stronger capability
ollama pull qwen3:8b

Tip: If VRAM isn’t enough, Ollama will automatically use a quantized version, or you can manually pull a quantized version like qwen2.5:3b-q4_K_M, which uses less VRAM.

5.8.3 Configure OpenClaw to Connect to Ollama

Configure OpenClaw to connect to local Ollama through Gateway:

openclaw config set 'models.providers.ollama' --json '{
  "baseUrl": "http://localhost:18789/v1",
  "apiKey": "ollama-local",
  "models": [
    { "id": "qwen2.5:3b", "name": "Qwen 2.5 3B" },
    { "id": "qwen2.5-coder:3b", "name": "Qwen 2.5 Coder 3B" },
    { "id": "qwen3:8b", "name": "Qwen 3 8B" },
    { "id": "phi3:mini", "name": "Phi-3 Mini" }
  ]
}'

# Set as default (3B model recommended; use qwen3:8b if you have 8GB+ VRAM)
openclaw models set ollama/qwen2.5:3b

Note: The Gateway address here is http://localhost:18789 (the port you specified when starting Gateway), not Ollama’s direct port 11434. This allows OpenClaw to centrally manage all model connections.

5.8.4 What is Gateway?

Gateway is OpenClaw’s backend service. You can think of it as a “translator”—OpenClaw talks to various models through it.

Simply put:

Gateway is responsible for centrally managing connections to various models
Gateway is responsible for handling authentication
Gateway is responsible for forwarding requests to different model providers

Architecture Diagram:

You
   ↓
OpenClaw CLI (where you enter commands)
   ↓
Gateway (manages connections)
   ↓
Model Providers
(MiniMax / Qwen / OpenRouter / Ollama)

Why is Gateway needed? Through Gateway as a unified entry point, OpenClaw can conveniently connect to various different model providers without configuring separate connection methods for each model.

5.8.5 Install Gateway

Gateway is usually automatically included when you install OpenClaw. If you need to install separately:

npm install -g @openclaw/gateway

5.8.6 Start Gateway

Gateway is OpenClaw’s core running process, responsible for:

Managing model connections
Providing HTTP / WebSocket API
Providing web control interface

Start Gateway (Recommended)

The simplest way is to run:

openclaw gateway run

This command starts the Gateway service. After starting, the default is:

http listener: //127.0.0.1:18789

You can open this address in your browser to access the web control interface for model configuration.

Common Parameters

If you need customization, you can use these parameters:

Parameter	Function	Example
`--port`	Specify port number	`--port 8080`
`--verbose`	Show detailed logs for troubleshooting	`--verbose`
`--force`	Force occupy the port	`--force`

Examples:

# Start with specified port
openclaw gateway run --port 8080

# Show detailed logs
openclaw gateway run --verbose

# Force occupy when port is in use
openclaw gateway run --force

5.8.7 Advanced Configuration (Optional)

If you want to further customize Gateway:

Option	Description
`--hot-reload`	Enable hot-reload, no restart needed for config changes
`SIGUSR1`	Send signal to restart Gateway (Linux/macOS)
`--config`	Specify config file path

Example:

# Hot-reload mode
openclaw gateway --port 18789 --hot-reload

Method 1: CLI Command Configuration

Use openclaw config set command to directly configure model parameters.

# Syntax
openclaw config set 'models.provider_name' --json '{
  "baseUrl": "https://api.example.com/v1",
  "apiKey": "your_API_Key",
  "models": [
    { "id": "model_id", "name": "display_name" }
  ]
}'

Example (Configuring MiniMax):

openclaw config set 'models.providers.minimax' --json '{
  "baseUrl": "https://api.minimaxi.com/v1",
  "apiKey": "your_MiniMax_API_Key",
  "api": "openai-completions",
  "models": [
    { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" }
  ]
}'

Pros: Fast, good for automation scripts Cons: Need to remember command syntax

Method 2: Edit Config File

Directly edit OpenClaw’s config file claude.json.

Config file location:

Windows: %USERPROFILE%\.openclaw\claude.json
macOS/Linux: ~/.openclaw/claude.json

Example Config:

{
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/v1",
        "apiKey": "your_MiniMax_API_Key",
        "api": "openai-completions",
        "models": [
          { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" }
        ]
      }
    }
  }
}

Pros: Batch configuration easy, easy to backup Cons: Need to manually edit JSON format

Method 3: Web Page Configuration (Recommended for Beginners)

Besides command line and config files, you can also configure models through the Web Interface. This method is more intuitive and suitable for beginners.

Step 1: Start Gateway

Gateway not only provides API services but also has a built-in web control interface. Run in terminal:

openclaw gateway run

This command starts the Gateway service and runs in the background.

Step 2: Open Browser to Access

Gateway’s web interface default address is:

http://127.0.0.1:18789

Open this address in your browser—you’ll see the Gateway management interface.

Step 3: Enter Configuration Page

Find and click in the interface:

Config → Models

Here you can manage all model configurations.

Step 4: Add Provider Configuration

Taking adding MiniMax as an example:

Click Add Provider or similar button
Select or fill in Provider type
Fill in the following information:

Field	Value
Base URL	`https://api.minimaxi.com/v1`
API Key	Your MiniMax API Key

Enable Auth Header option (if needed)
Fill in API Key

Step 5: Save Configuration

Click Save or Update button to save the configuration.

Tip: After saving, Gateway will automatically refresh the config. You may need to restart OpenClaw for changes to take effect.

The benefits of this method:

Visual operation, no need to remember commands
See configuration status in real-time
Suitable for users unfamiliar with command line

6. Using cc-switch to Manage APIs (Recommended)

If you’ve configured multiple model providers, manually changing config each time can be tedious. cc-switch is a cross-platform desktop tool that helps you switch between different AI API configurations with one click. It supports Claude Code, OpenClaw, Gemini, and more.

6.1 Why Use cc-switch?

Problems with manually managing API Keys:

Need to separately configure environment variables for each provider
Switching models requires modifying JSON config
Easy to get confused with multiple accounts/providers

cc-switch advantages:

Visual interface, no need to edit command line configs
One-click provider switching
Supports MCP server management
Supports Skills/Prompts presets

6.2 How cc-switch Works

Important: cc-switch writes the currently enabled provider configuration to environment variables. When OpenClaw starts, it automatically reads these environment variables, so you don’t need to manually edit OpenClaw’s config file.

This is the convenience of cc-switch: you just switch the provider in cc-switch, then start OpenClaw, and it will automatically use the current configuration.

6.3 Install cc-switch

Windows:

Visit cc-switch GitHub Releases
Download CC-Switch-v{version}-Windows.msi or portable version
Run the installer

macOS:

brew tap farion1231/ccswitch
brew install --cask cc-switch

Linux:

Supports .deb, .rpm, .AppImage and other formats.

6.4 Add Provider

Start cc-switch
Click ”+” in the top right or “Add Provider”
Select preset provider (MiniMax, Qwen, etc.)
Fill in your API Key
Click “Add”

6.5 Switch Provider

In the main interface, select the provider you want to use
Click “Enable”
Restart OpenClaw (if it’s running)

6.6 OpenClaw Automatically Uses Current Config

cc-switch writes the currently enabled provider configuration to environment variables. When OpenClaw starts, it automatically reads these environment variables, so you only need to:

# After switching provider, restart OpenClaw
openclaw restart
# or
openclaw serve

OpenClaw will automatically use the API configuration currently enabled in cc-switch.

7. Starting and Using

After configuring the model, you’re ready to use it.

# Interactive chat
openclaw

# Start web service
openclaw serve --port 3000

# Start Gateway (if not auto-started)
openclaw gateway run

# Web panel
openclaw dashboard

Just type text to chat. If tools are configured, it can also help you operate files, search for information, and more.

8. Recommended Configurations

For different scenarios, here’s a reference:

Scenario	Recommended Model	Reason
Programming	qwen/qwen3-coder	Specifically optimized for coding, good GitHub integration
Vision Understanding	qwen-portal/vision-model	Supports image understanding
Daily Chat	MiniMax-M2.5	Good Chinese understanding, great cost-performance
Deep Reasoning	Qwen3-Max	Strong capability
Local Offline	Ollama qwen2.5:3b	Mainstream config usable, completely free

My usual combo: Use MiniMax for daily use, switch to qwen/qwen3-coder for programming.

Switching models is easy:

# Switch to MiniMax
openclaw models set minimax/MiniMax-M2.5

# Switch to Qwen for programming
openclaw models set qwen/qwen/qwen3-coder

# Switch to Qwen Vision
openclaw models set qwen/qwen-portal/vision-model

9. Common Issues

Command Not Found

# Check if installed
npm list -g openclaw

# Restart PowerShell and try again

# If still not working, reinstall
npm install -g openclaw@latest

API Key Error

Check if Key is correct, no extra spaces
Check if there’s still balance
Recommended to use environment variable method

Ollama Connection Failed

# Confirm Ollama is running
ollama list

# Try accessing
curl http://localhost:11434

Gateway Connection Failed

# Confirm Gateway is running
openclaw gateway run

# If port is occupied, add --force to force start
openclaw gateway run --force

# Or specify another port
openclaw gateway run --port 8080

Response Too Slow

Remote API: Check network, or try another model
Ollama: Consider using smaller models like qwen2.5:3b or quantized version qwen2.5:3b-q4_K_M

Installation Script Error

Confirm execution policy is changed:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

10. Alternative: Tencent Workflow AI (WorkBuddy)

If you find OpenClaw deployment too complicated, consider Tencent Workflow AI (also known as WorkBuddy).

What is WorkBuddy?

WorkBuddy is an AI programming assistant released by Tencent, similar to Cursor and Windsurf products. It doesn’t require local deployment—just use VS Code or JetBrains plugins directly.

Features

No deployment needed: Install plugin and use immediately
Generous free credits: Tencent provides free usage quotas
Well-optimized for Chinese: Friendly for Chinese developers
Integrates Tencent ecosystem: Can connect to WeChat, Tencent Cloud, and other services

Who It’s For

Programming beginners who don’t want to deal with environment setup
Those who want a plug-and-play experience
Those who simply want to experience AI programming assistance

Comparison with OpenClaw

Feature	OpenClaw	WorkBuddy
Deployment	Local deployment	No deployment needed
Customization	High	Medium
Learning curve	Higher	Lower
Cost	Free/Paid	Has free credits

Summary: If you just want to experience AI programming assistance, WorkBuddy is a simpler choice. If you want higher customization and scalability, OpenClaw is still the better choice.

Conclusion

This tutorial might still not be detailed enough, but I’ve written a very basic detailed configuration tutorial. I’ll update with more detailed LLM parameter explanations later. I may also update detailed tutorials on integrating OpenClaw with Feishu and more.

如何注册一个 Cloudflare 域名

Sun, 08 Mar 2026 00:00:00 GMT

前言

我前段时间打算给我的博客网站增加一些功能，例如 GitHub 登录、Cloudflare 全家桶、SEO 优化什么的，很可惜。都因为我没有域名，总是因为一些原因而失败。于是我想了想，一年几十块买个域名，也不算贵，因为我之前也搞过，只不过不是我出钱。

为什么选择 Cloudflare 注册域名？

Cloudflare Registrar 最大的特点是不赚差价。它不像传统注册商那样靠域名盈利，而是以此作为进入其生态系统的入口。

真正的批发价：Cloudflare 承诺永久以成本价销售域名。你支付的每一分钱都是直接交给注册局，CF 不加收任何服务费，且续费价格固定，没有“首年低价、次年暴涨”的套路。
免费隐私保护：默认提供 WHOIS 隐私保护，隐藏你的姓名、邮箱和地址。而在其他平台，这可能是一项年费支出。
顶级安全防护：免费赠送企业级 DNSSEC 防止域名劫持，并支持硬件密钥（如 YubiKey）登录，安全性拉满。
管理一步到位：如果你打算用 Cloudflare 部署博客，域名在这里买可以省去修改 DNS 的等待时间，证书申请和解析都是秒级自动完成。

所以在 Cloudflare 购买域名算是批发价格了，我下面提供一个表格，来对比一下 Cloudflare 和阿里云、腾讯云之类的区别。

维度	Cloudflare	传统云厂商 (阿里/腾讯/Namecheap)
定价	成本价，无溢价	市场价，首年优惠次年贵
隐私保护	默认免费开启	免费或需额外购买
管理体验	开发者友好，集成度极高	功能分散，配置较多
备案支持	不支持国内工信部备案	支持国内工信部备案

Cloudflare唯一存在一点不足，那就是不支持国内工信部备案，所以根据你的需求，是否一定要做工信部备案。对于我而言，我觉得目前不是特别有必要，我的服务托管到Cloudflare上了，唯一的支出也就域名了还能接受，并且白嫖Cloudflare的CDN国内访问也不是太大问题。如果我后续可能几年后有需要国内备案，那我就得再去整个国内服务器，还要买个国内域名了。

所以对于不打算备案、使用 Cloudflare 生态的个人博客来说，CF 就是域名的终点站。

准备工作

Cloudflare 账户
Visa 银行卡或者 PayPal

如果你还没有注册 Cloudflare 账户，那就注册一个，Google 账号登录或者 GitHub 登录即可，点击该超链接。

对于 Visa 卡和 PayPal，对于国内读者可能有点难办了，因为需求原因，平时都没有用过。如果你找不到个哥们什么的帮你代付，你只能自己想办法了，很多银行其实有提供给学生的支持 Visa 的信用卡，以下内容我以工商银行的星座卡学生办举例（没有支付问题的朋友可以自行跳过，并非广告，解决国内学生朋友的问题）。

支付准备工作

此处以工行星座卡校园版申请举例

申请条件：需本科以上学历，学生卡尽量不超过2~3张（1+1套卡算1张），网贷（花呗，白条等）账户尽量不超过2个（其实一般你不乱搞什么的都有资质办理）

星座卡特点：

银联（人民币）+Visa（外币）套卡，卡等级为普卡，有效期内免年费（约等于永免）。
绝大部分地区的校园版是0额度！非校园版需有实习/工作单位。
11币种账户，但对征信无碍，放心申。

申请步骤：

打开中国工商银行app，点击顶部的搜索框输入星座卡学生办
在页面中产品一栏，选择宇宙星座卡校园版（VISA+银联）
按照流程填写信息，以及信用卡的邮寄地址
等到银行卡拿到后，你就可以去线下网点激活了

当然你也可以直接去线下网点办理，不过要注意不要异地办理，例如你可能填写的注册银行是你家那边的支行，但是你在外省读大学，可能到了外省的线下网点就无法激活了，所以还是建议选一个你方便激活的银行地址。

转换美元

打开中国工商银行app，点击顶部的搜索框输入美元兑换
在产品栏看到结售汇，点击选择购汇
币种选择美元然后按照你的需求购买
受到短信后检查一下对应银行卡的美元余额

记住不要美元余额刚刚好是你的域名价格，因为境外网站可能对支付会有最低额度的设置。

我还是很建议你办一张Visa卡，总有用到的时候。

Cloudflare 注册域名步骤

点击进入以下网址 https://www.cloudflare.com/zh-cn/products/registrar/，你可以看一下 Cloudflare 的域名注册介绍，这个网址也很容易搜到，在搜索引擎搜查 Cloudflare 域名购买就可以直达。你也可以选择左侧导航面板点击：域注册 → 注册域，或者直接点击链接访问：https://dash.cloudflare.com/domains（右上角可以选择切换语言）

搜索你需要的域名，我们以danarnoux为例，可以看到有很多后缀的域名

至于这些域名后缀代表什么，我为您提供一份表格进行参考

后缀	类型	建议使用场景	特点
.com	通用	首选。个人博客、品牌、商业	全球认可度最高，用户心智首选，利于 SEO。
.net	通用	网络服务、技术博客、替代方案	历史悠久，专业感强，常作为 .com 被占用后的备份。
.org	非营利	开源项目、社区、公益组织	带有信任感和权威性，适合非营利性技术社区。
.io	技术	技术博客、开发者工具、初创公司	在程序员圈子极受欢迎，代表 Input/Output，极简且酷。
.me	个人	个人简历、生活随笔、作品集	个性化极强，非常适合强调“自我”品牌的个人博客。
.info	信息	知识库、资讯网站、说明文档	价格通常较便宜，适合做纯信息展示类项目。
.dev	开发者	编程教程、代码库、开发日志	谷歌推出的后缀，强制 HTTPS 安全加密，极具辨识度。

你可能会注意到.uk的价格比.com接近便宜一倍，那我是不是可以购买这个？我的建议是，这个便宜还是不贪为妙

.uk 是英国（United Kingdom）的国家代码顶级域名（ccTLD）。它由 Nominet 机构管理，类似于中国的 .cn 或美国的 .us。可以购买，但有“英国地址”要求。如果你没有英国地址，很多注册商（包括 Cloudflare）可能会拒绝你注册，或者要求你使用代理服务。如果你随意填写虚假的英国地址，一旦被管理机构抽查，域名可能会被直接封禁（Suspended）。

权衡一下，选择你想要的域名即可。记得注意一下有无被注册以及续费价格。

购买 Cloudflare 域名

选择好域名后，点击Confirm确认
按年计费，选择你要购买的年份，注意选择支付方式后的 Automatic renewal（自动续期），选择是否勾选
填写相关信息，以及发票信息
选择银行卡支付的时候，一定要注意不要输错安全码，输错三次银行卡会被锁，后续只能挂失新开一张银行卡了。（银行卡）
如果你支付的时候出现银行卡被拒绝的情况，检查一下账户内美元余额，安全码是否输错，卡号是否输对，实在不行可以联系银行客服。在我支付的时候，还出现了一种问题，估计是地理位置和ip不一致被支付网关拒绝了，说人话就是我停止使用香港节点进行支付成功了。如果你也出现了这种情况，可以试试，只是支付会慢一点。
支付成功后，检查邮箱的发票以及银行卡余额。
去左侧仪表盘内点击Domains，检查是否存在购买的域名。

域名解析与 DNS 设置

点击左侧面板的 Domains，点击右侧的三个点进入配置页面配置 DNS。

可以参照我的设置选择 CNAME 进行解析，打码的内容为不重要，Cloudflare Proxy（即橙色云）可默认勾选，提升网站速度和安全性。设置完后记得保存

结语

对于 SSL/TLS 加密的内容本篇文章不再赘述，一般情况下 Cloudflare 会默认给域名配置通用证书。后续我会提供更多内容，例如如何做好 SEO，如何做 GitHub OAuth 等内容。敬请关注

Video Guide:【Cloudflare域名注册教程|step by step|包含支付问题解答】 https://www.bilibili.com/video/BV1tvc6z1EfD/?share_source=copy_web&vd_source=b29b2491306fe84f395d46cf297dc405

Cloudflare Domain Registration Guide

Tue, 17 Feb 2026 00:00:00 GMT

Introduction

I wanted to add some features to my blog lately—GitHub login, Cloudflare ecosystem, SEO optimization, you name it. Problem is, I didn’t have a domain name. Every time I tried to set something up, it just… failed because of that. So I figured, why not just buy one? It’s not that expensive—maybe a few dozen bucks a year. I’ve done this before anyway, just never paid for it myself.

Why Choose Cloudflare for Domain Registration?

Cloudflare Registrar stands out because they don’t markup prices. Unlike traditional registrars that profit from domain sales, Cloudflare uses domains as a gateway to their ecosystem.

True wholesale pricing: Cloudflare promises to sell domains at cost forever. Every penny you pay goes directly to the registry—no hidden fees, and renewal prices stay the same. No “cheap first year, expensive second year” tricks.
Free privacy protection: WHOIS privacy protection comes standard, hiding your name, email, and address. Other registrars often charge extra for this.
Top-tier security: Free enterprise-grade DNSSEC to prevent domain hijacking, plus hardware key support (like YubiKey) for login. Maximum security.
All-in-one management: If you’re deploying on Cloudflare anyway, buying your domain here saves you the DNS wait time. Certificate requests and DNS resolution happen automatically.

Here’s a quick comparison:

Aspect	Cloudflare	Traditional Registrars (Aliyun/Tencent/Namecheap)
Pricing	Cost price, no markup	Market price, cheap first year, expensive renewal
Privacy	Free by default	Free or extra cost
Experience	Developer-friendly, high integration	Feature-spread, more config needed
ICP License	Not supported (China MIIT)	Supported (China MIIT)

One downside: Cloudflare doesn’t support China MIIT ICP filing. Whether you need that depends on your situation. For me, it’s not really necessary—my hosting is on Cloudflare, the only real cost is the domain, and Cloudflare’s CDN works fine in China. If I ever need ICP filing later, I’d need to get a Chinese server and a Chinese domain.

So if you’re not planning to file in China and you’re using Cloudflare’s ecosystem, Cloudflare is the endpoint for domains.

Prerequisites

Cloudflare account
Visa card or PayPal

If you don’t have a Cloudflare account yet, just sign up with your Google or GitHub account.

Payment Prep (ICBC Student Card Example)

For international payments like Visa or PayPal, it can be tricky if you’re in China. If you can’t find someone to help you pay, you’ll need your own solution. Many banks offer Visa cards for students—here’s an example with ICBC’s Star Sign Card (this is just to help fellow students, not an ad).

Application requirements: Undergraduate or above, try to keep student cards under 2-3, online loans (Huabei, Baitiao, etc.) under 2 accounts.

Card features:

UnionPay (CNY) + Visa (foreign currency) combo card, regular card, free annual fee.
Campus version has 0 credit limit in most regions! Non-campus version requires work/internship proof.
11 currency accounts—doesn’t affect credit score.

Application steps:

Open ICBC app, search “星座卡学生办” (Star Sign Student)
Select 宇宙星座卡校园版 (VISA + UnionPay)
Fill in your info and mailing address
Once you get the card, activate it at a nearby branch

Note: Don’t apply in a different city from where you registered. If your bank is in your hometown but you’re studying in another province, you might not be able to activate it. Pick a convenient location.

Converting to USD:

Open ICBC app, search “美元兑换”
Select 结售汇 → 购汇
Buy USD as needed
Check your card’s USD balance after getting the SMS

Don’t just have exactly enough USD for your domain—some international sites have minimum payment amounts. Worth getting a Visa card anyway, you’ll use it eventually.

Cloudflare Domain Registration Steps

Go to https://www.cloudflare.com/products/registrar/ to learn about Cloudflare’s domain registration. You can also find it by searching “Cloudflare domain purchase” or go directly to https://dash.cloudflare.com/domains.

Search for your desired domain. Let’s use danarnoux as example—you’ll see many TLD options.

Here’s a quick reference for common TLDs:

TLD	Type	Best For	Notes
.com	Generic	Top choice. Blogs, brands	Highest recognition, good for SEO.
.net	Generic	Tech blogs, network services	Professional, good .com backup.
.org	Non-profit	Open source, communities	Trustworthy, great for non-profit tech communities.
.io	Tech	Tech blogs, dev tools	Super popular among programmers.
.me	Personal	Resumes, portfolios	Perfect for personal branding.
.info	Info	Knowledge bases, docs	Usually cheaper, good for info sites.
.dev	Developer	Tutorials, code repos	Google-owned, forced HTTPS, very recognizable.

You might notice .uk is much cheaper than .com. My advice? Don’t chase the cheap price.

.uk is the United Kingdom’s country code TLD, managed by Nominet (like .cn for China or .us for the US). You can buy it, but there’s a UK address requirement. Without a UK address, many registrars (including Cloudflare) might reject your registration or require proxy services. If you provide a fake UK address, the domain could get suspended during random audits.

Just pick what you want. Remember to check availability and renewal prices.

Buying the Domain

Select your domain and click Confirm
Choose your billing period (years). Decide whether to enable Automatic renewal
Fill in your details and invoice info
When paying with card, be careful with the security code—three wrong attempts locks your card. You’ll need to report it lost and get a new one.
If your card gets declined, check your USD balance, verify the security code and card number. Contact your bank if needed. One issue I ran into: payment gateway rejected me because of location/IP mismatch. I stopped using Hong Kong nodes and it worked. Try it if you have similar issues—just might be slower.
Check your email for the invoice and card balance.
Go to Domains in the sidebar to confirm your purchased domain is there.

DNS Settings

Click Domains in the sidebar, then the three dots to configure DNS.

You can follow my setup—use CNAME for analysis. The redacted parts aren’t important. Cloudflare Proxy (the orange cloud) should be enabled by default for better speed and security. Don’t forget to save.

Wrapping Up

I won’t go into SSL/TLS details here—Cloudflare sets up a universal certificate by default. I’ll cover more in future posts, like how to do SEO right and GitHub OAuth. Stay tuned!

Video Guide: https://www.bilibili.com/video/BV1tvc6z1EfD/?share_source=copy_web&vd_source=b29b2491306fe84f395d46cf297dc405

如何上手编程：工具、Git 与工程思维

Tue, 17 Feb 2026 00:00:00 GMT

前言

我一直认为，人无法想象自己认知以外的事。尽管现在AI再这么强大，你或许还是没法用ai搓出一个满意的作品。你也有时候会焦虑，既然ai这么强大，那我学怎么编程还有意义？岂不是后面程序员都会被AI代替了？

我知道你有很多疑惑，但是在我看来，时代在变化答案每天都在改变，今天适用的法则未必适用于明天，明天适用的法则也不一定适用于今天。比起一切浑然不知云里雾里，我更希望你对一个事物有所了解，毕竟其实这世上也没有什么神秘的事情。如有必要，最好亲身接触一下，我一直很喜欢一句话：“实践是检验真理的唯一标准”。

学习一项技能是一个很光荣的事情，也会成为你一个终生的爱好。在我看来，无论看文章的你是个中学生，还是个刚上大学的大学生，都有必要学习如何使用计算机甚至写代码做项目。

在我看来，所有人其实都有某一方面的天赋，只是受其环境或者经历原因，未被发掘出来而已，也许我每天都与未来的天才擦肩而过，而他们对此浑然不知。我更希望，所有有希望的学生都在年少时被一个偶然的经历激发起了对一件事的兴趣，然后开始培养一个爱好。

对于我自己来说，我是浙江人，高中有门选考科目是技术，信息技术那块学的是Python。那会我们学校有个oj做题网站，大家都喜欢占着电脑做题，也在闲暇之余我们也研究过一些有趣的东西，殊不知这些东西也算是改变我们人生道路的一个开始。

无论你是做工程的人，还是学文科的人，我觉得都有必要知晓其概念，这样当你做决策的时候，我不能保证你不会再迷茫，或许知道更多你会更加迷茫了，但你的脑海内会出现一个大大的问号，你开始有方向的进行思考了。

1. 什么是编程

编程没那么神秘，它更像一种工程表达能力：把问题拆开，把步骤排好，再让机器稳定执行。

你不需要一开始就懂所有底层。先记住一件事：你写的不是炫技语法，而是一套能复现、能排错、能维护的流程。

1.1 计算机体系里编程在什么位置

你可以把这件事想成一条从下到上的链路。最下面是硬件，CPU、内存、硬盘都在这一层。CPU 还有自己的架构（x86、ARM），它决定了机器能听懂哪一套指令。

再往上是操作系统（Windows / Linux / macOS）。它负责把硬件管起来，再给程序一套统一入口。你写代码时调用文件、网络、窗口，背后都是系统在接住。

编程语言在中间扮演翻译层。你写的是 Python 或 C，机器最后执行的是更底层的指令。最上面才是应用程序，也就是你每天点开的浏览器、编辑器，或者你自己写的小工具。

Windows 和 Linux 是什么？

Windows 和 Linux 都是操作系统，不是编程语言。你可以这样理解：它们是“管家”，负责把硬件资源分配好，再把规则定清楚。

我见过很多新手一开始会把“会用 Windows”当成“会编程”，这很正常。操作系统更像是运行环境，它决定程序怎么访问文件、怎么申请内存、怎么跟设备打交道。

系统是舞台，程序是演员，语言是你写剧本的方式。把这三个角色分开，后面很多概念就不容易混。

1.2 路径与目录：Path、根目录、相对路径

路径你可以继续理解成地址和门牌号。程序去找文件，其实就是在问“它具体放哪儿了”。

比如 C:\Users\Dan\Desktop\learning\hello.txt，这是完整门牌号；你在终端里用 cd，就是先把自己走到正确楼层，再去拿文件。

这里有个很常见的小坑：路径里不是说中文一定不行，但在一些工具链、编码设置、老库或命令行组合里，中文目录名偶尔会出幺蛾子。为了少踩坑，平时尽量用英文路径名会更稳，比如 test、folder、project、data、output 这种短词就很好用。

什么是根目录

在 Windows 里，C:\ 就是一个“根”。你可以把它想成省级入口，下面再分用户目录、项目目录、数据目录。路径一长，其实就是从这个入口一层层往下走。

什么是相对路径

相对路径是“相对于你当前所在目录”的写法。绝对路径像 C:\Users\Dan\Desktop\learning\hello.txt，一步到位；相对路径像 .\hello.txt 或 data\input.txt，默认从你当前站的位置出发。

相对路径报错最常见的原因，不是文件不存在，而是你站错目录了。你以为自己在 learning，其实终端还停在上一级，这时候路径当然会找不到。

Windows 用户可跳过这一小段：
Mac 的根目录是 /，个人目录通常是 /Users/你的用户名。
相对路径规则不变，常见写法还是 ./、../。

1.3 架构差异：x86 vs ARM

x86 和 ARM 是两种主流 CPU 架构，可以当成两种不同的“机器方言”。传统 PC 长期以 x86 为主，手机和平板基本是 ARM，新款 Mac（Apple Silicon）也是 ARM。

你写的代码最终都要翻译成目标架构能执行的指令。慢慢你就会发现，同一份代码换到不同设备上，偶尔会遇到兼容性差异，这不是你写错了，很多时候只是底层平台不同。

编程语言在这套体系中的位置

这里最容易混淆。Python 不是系统，C 也不是 CPU。语言更像翻译层，把你的想法组织成机器能执行的形式。

把这个位置想明白后，你看“系统报错”“解释器版本”“架构兼容”这些词就不会混成一团。

1.4 编程基本概念：流程、脚本、变量、编码

举个很接地气的例子：把下载目录里的图片统一改名。你要先找到目标目录，再筛出 .jpg / .png，然后定好排序和命名规则，最后把失败项记下来重试。

你会发现，真正重要的是步骤设计，不是某个语法点背得多熟。这就是算法思维。语言只是工具，流程才是核心。

什么是脚本？

脚本（script）就是为具体任务写的小程序，重点是“省重复劳动”。

比如每天整理下载目录、批量改文件名、自动汇总文本，这些都很适合脚本。它未必复杂，但非常实用。

什么是变量？

变量就是给数据起名字。名字起得好，你过几天回来看还能一眼看懂；名字起得随便，代码就会很快变成谜语。

比如统计图片数量，用 image_count 基本不用解释；写成 a1，三天后你自己都要猜半天。我当年第一次写脚本时就吃过这个亏，代码能跑，但一个月后根本不想再碰。

变量看起来是小事，实际上它直接影响可读性，也影响你后面的排错速度。

什么是编码？

换个角度想，编码不是打字比赛，而是组织能力。你在做的是把一个想法拆成可执行的结构：变量怎么放、流程怎么走、函数怎么分、模块怎么拆。这里说的“编码”，指的是写代码、把想法组织成程序，不是 UTF-8 这类字符编码。

结构清楚，后面改需求会轻松很多。结构混乱，功能越加越痛苦。你现在不懂也正常，先从“写完自己能看懂”这件事开始就行。

1.5 英文与报错阅读：重要但别焦虑

不用把这件事搞成压力竞赛。你不是先背完词典才能学编程。我不建议你因为学编程而现在开始准备学英语，而是边做边学。

但有一件事很现实：你迟早要看英文报错、英文文档、英文 issue。能不能读懂关键内容，会直接影响你的排错速度。

所以目标不是“英语满分”，而是“能看懂核心技术词，能读懂自己写的变量名和错误信息”。

1.6 新手误区与起步心态

我见过很多新手会卡在几个差不多的地方：只背语法不做项目，只看视频不动手，一报错就停，把 AI 当魔法不做验证，总想“再准备一下”结果一直不开工。首先对于ai来说，你啥也不知道就让他做个网站，有点像遇到不知具体需求的甲方了，大概率得到的结果不如你所愿。

这些都不是能力问题，更多是节奏问题。先做一个很小的可运行结果，再逐步加复杂度，心态会稳很多。

先选路线，再装工具

很多新手最容易卡在“环境要怎么装”，结果还没开始写代码就已经疲惫了。

我更建议你先把方向定下来：第一门语言先 Python，然后用最小路线跑通“写 -> 跑 -> 改”。

你先有“能跑起来”的体验，再回头看工具细节，心态和效率都会好很多。下面先讲语言选择，再讲环境搭建。

2. C 还是 Python？

这一节我给一个稳妥建议：第一门语言先学 Python。无论你是文科、理工、转行，还是在校生，先 Python 都更容易建立正反馈。

2.1 为什么先 Python

Python 最大的优势是反馈快。你写几行就能看到结果，这对新手特别重要，因为你会持续获得“我确实在前进”的感觉。当你在做一件事，如果能及时得到正反馈，你反而会越来越感兴趣进步的越来越快，我不是很希望一上来就整太难的人你收获满满的挫败感。

它的语法也比较直观，资料和社区都很成熟，遇到问题通常能查到可用答案。我见过很多新手不是因为难度放弃，而是因为长期没有正反馈。Python 在这件事上确实更友好。

2.2 Python 10 分钟入门（写到循环为止）

先说清楚范围：这一段只带你走到循环，够你跑出第一个小程序。后面的函数、列表、字典、文件先不展开。当前内容可以在后面配完开发环境后进行验证，你也可以直接跳过到2.4

变量这件事可以当成“给数据起名字”，名字清楚，代码就好读。

name = "Dan"
age = 18
print(name, age)

运行后你应该看到一行输出，比如 Dan 18。

print() 是输出，input() 是输入。input() 拿到的是字符串，想做数字运算要先 int()。

age = int(input("请输入你的年龄："))
print("明年你是", age + 1, "岁")

运行后你输入一个数字，会看到“明年你是 xx 岁”。

if 就是条件判断，满足条件才执行对应分支。

score = 72
if score >= 60:
    print("及格")
else:
    print("再练练")

运行后你会看到 及格（因为示例分数是 72）。

for 常用于“按次数重复”。range(5) 是 0 到 4，range(1, 6) 是 1 到 5。

for i in range(1, 6):
    print(i)

运行后会按行输出 1 到 5。

while 适合“满足条件就继续循环”。比如累计到 100 就停：

total = 0
n = 1
while total < 100:
    total += n
    n += 1
print(total, n - 1)

运行后会输出累计结果和最后一次加到的数字（例如 105 14 这种形式）。

2.3 自学入口与小作业

到循环为止你就有了起步能力，后面的函数、列表、字典、文件、模块建议自己学。核心不是“背完”，而是会查资料、会读文档、会验证结果。

自学入口可以先用菜鸟教程：https://www.runoob.com/。遇到新语法别急着全记，先跑一个最小例子看它到底做了什么。

给你一道小作业，先做出结果，再慢慢优化：

水仙花数（也称为自恋数或阿姆斯壮数）是指一个 n 位数，其各个数字的 n 次方和等于该数本身。例如，三位数的水仙花数是指一个三位数的每个数字的立方和等于该数本身。计算方法如下：将三位数的每个数字提取出来，计算这三个数字的立方和，判断这个和是否等于原数。我需要你找出（100~999）的水仙花数
提示：拆成百位/十位/个位，算三次方后比较是否等于原数。

2.4 Python 的应用场景与语言对比

它的应用非常广。文科方向可以做文本分析、表格清洗和可视化；经济金融方向常见是指标计算和报表自动化；地理方向也能处理云图和空间数据。理工科这边也很好落地，比如实验数据清洗、批量画图、参数扫描、简单数值计算，很多重复步骤都能脚本化。再往工程一点走，自动化脚本、Web 后端、AI 数据预处理和训练脚本都很常见。你不需要一次全学会，先在自己最有感觉的场景里做出一个小结果，学习效率会高很多。

Python vs C：看一个最小示例

同样是打印 1 到 5：

Python：

for i in range(1, 6):
    print(i)

C：

#include <stdio.h>

int main() {
    for (int i = 1; i <= 5; i++) {
        printf("%d\n", i);
    }
    return 0;
}

这个例子不是为了说明谁“更高级”，只是让你直观看到入门阻力差异。

2.5 C 以后要不要学

要不要学，答案是：看方向。你先用 Python 建立编程直觉，后面如果要做底层、性能、系统方向，再补 C 会更顺。

一条最小起步路线

先学 Python 基础（变量、分支、循环、函数）。
写一个能跑的小脚本（比如批量改名）。
遇到报错就查、就改、就复跑。

这条路线跑通一次，入门就稳了。

3. 开发环境搭建

3.1 编辑器与 IDE：为什么先用 VS Code

如果你刚开始学，我更倾向先用 Visual Studio Code。

先说一下 IDE 这个词。IDE（Integrated Development Environment，集成开发环境）可以理解成“工具全家桶”，里面通常包含编辑器、调试器、运行器、项目管理这些能力。像 PyCharm、Visual Studio 都属于这一类。

我不建议新手一上来就用重型 IDE，不是因为它们不好，而是功能太多时你容易被界面带着走，反而看不清“代码到底怎么跑起来”。入门阶段更重要的是把这条底层流程先摸熟。

VS Code 的好处是，它介于纯编辑器和重型 IDE 之间：默认轻量，按需扩展，够用但不过度。这个平衡对新手很友好。

原因很实际：跨语言、插件生态成熟、内置终端够用、Git 集成也顺手。新手阶段工具越统一，心智负担越小。

我当年第一次装环境也卡过，界面里一堆选项看得人头大。这很正常，先把工具链跑通，后面再慢慢调习惯。

官网地址在这：https://code.visualstudio.com/。

先装最少插件，够用就行：

Python（ms-python.python）
Pylance（ms-python.vscode-pylance）
Markdown All in One（yzhang.markdown-all-in-one）
GitLens（eamodio.gitlens，可选）

3.2 Python 插件与解释器：VS Code 里到底做什么

这个问题新手很容易混淆。Python 和 Pylance 插件主要做的是编辑器能力：语法高亮、补全、跳转、类型提示、调试入口这些。

它会让你写代码更顺手，但它本身不是 Python 解释器。那句最关键的话是：VS Code 里装了 Python 插件，不代表电脑里装了 Python。

再补一句更本质的话：VS Code 主要是“写代码和组织工程”的工作台，不是运行时本体。它可以调用你电脑里的终端、解释器和 Git，但它不会替你装好 Python 本体。你在 VS Code 里能不能跑 python，最终还是取决于你系统里有没有可用解释器，以及路径有没有配对。

你在 VS Code 里看到的“Select Interpreter（选择解释器）”，本质上也是在告诉编辑器：这次项目要调用你电脑上的哪一个 Python。

你可以直接这样操作一遍：打开 VS Code，按 Ctrl + Shift + P，输入 Python: Select Interpreter，然后选择你刚创建的 learn 环境。如果这里选错，VS Code 可能运行的就不是你刚安装的那套 Python。

选对之后，状态栏通常会显示当前 Python 环境或版本（不同主题位置会有点差异），这是你是否切换成功的一个直观信号。

3.3 VS Code 安装、中文语言包与插件

先按最稳流程走一遍，别一上来改太多选项。

去 VS Code 官网下载 Windows 安装包。
你应该看到明显的 Download for Windows 按钮。
安装时建议勾选：
- Add to PATH
- Open with Code
- （可选）Register Code as an editor for supported file types
安装完成后启动 VS Code。
你应该能看到左侧活动栏（Explorer/Search/Source Control/Run/Extensions）。
打开扩展市场（左侧方块图标 Extensions），搜索并安装简体中文语言包：
Chinese (Simplified) Language Pack for Visual Studio Code（Microsoft 官方）。
安装后按提示重启 VS Code。
重启后界面会切到中文（如果没自动切，可在命令面板手动切换显示语言）。
如果你习惯繁体，也有对应语言包可装：
Chinese (Traditional) Language Pack for Visual Studio Code。
第一次打开后再做三件事：
- 语言切到你习惯的界面。
- 安装上面的最少插件清单。
- 按 Ctrl + ~ 打开终端，确认可以正常输入命令。

Windows 用户可跳过这一小段：
VS Code 官网同样提供 macOS 版本：https://code.visualstudio.com/。
装好后直接打开即可，插件安装和解释器选择逻辑与 Windows 基本一致。

什么是开发环境？

开发环境可以理解成你的“编程工作台”。编辑器负责写代码，解释器或编译器负责把代码变成可运行结果，终端是你下命令和跑程序的入口。

包管理器（比如 pip、conda）用来装和管理依赖，运行时则决定代码真正执行时依赖的条件。你不需要一次全部吃透，先知道这些部件是在配合工作就够了。

3.4 终端与 Win+R：先把命令行跑通

CMD，powershell，vscode里的终端，他们都又是什么呢？

刚开始你可能觉得黑框很可怕，但它只是一个输入命令的地方。

它们本质都是命令行入口。CMD 更直接，适合先上手；PowerShell 功能更丰富；VS Code Terminal 本质上是把这两者放进编辑器里，少切几个窗口。

先固定一个就够，我建议先用 CMD。

先记住几条最常用的就够：cd 切目录，dir 看文件，mkdir 建目录，rmdir 删空目录，echo 输出文本，cls 清屏。

做个 3 分钟练习（可直接复制）：

mkdir "%USERPROFILE%\Desktop\learning"  # 创建 learning 文件夹
cd /d "%USERPROFILE%\Desktop\learning"  # 进入 learning 文件夹（/d 支持切换盘符）
echo Hello Programming > hello.txt      # 创建并写入 hello.txt
dir                                     # 查看当前目录内容
type hello.txt                          # 查看文件内容
mkdir temp                              # 创建 temp 子文件夹
rmdir temp                              # 删除空的 temp 子文件夹
cls                                     # 清空终端屏幕

你大概率会看到：执行 dir 之后列表里有 hello.txt，执行 type hello.txt 会输出 Hello Programming。

常见坑也就两个：一是忘了 cd /d，盘符没切过去；二是没进 learning 就建文件，结果文件跑到别的目录里。

如果你能看懂每条命令在做什么，终端这关就过了第一步。

怎么打开系统命令行（Win + R）

如果你不在 VS Code 里，也可以直接开系统命令行。按 Win + R，输入 cmd，回车，就会打开 Windows 的命令提示符。

打开后你通常会看到类似 C:\Users\你的用户名> 的提示符，这就是你当前所在目录。

如果你不小心开成了 PowerShell 也不用慌，大多数基础命令照样能跑，先把流程走通最重要。

VS Code 底部那个终端，本质上也是在调用这套命令行环境，只是它被放在编辑器里了。你在两边输入的很多命令是同一套逻辑。

Mac 用户可跳过 Windows 这段：
Mac 上打开“终端 Terminal”即可，Spotlight 搜索 Terminal 很快能找到。
命令大多相同，只是 Windows 常见 cmd，Mac 常见 bash/zsh。

3.5 Python 本体、Miniconda 与安装路线

我推荐Miniconda，其实可能 Anaconda会更好但是我还是希望你能熟悉一下终端操作。

我依旧推荐 Miniconda，原因是轻量、可控、环境隔离体验好。

Miniconda 官方下载页：https://docs.conda.io/en/latest/miniconda.html。

先记三个词：Python 版本（比如 3.10、3.11）、包（比如 requests 这种第三方库）、虚拟环境（每个项目各用各的依赖，互不干扰）。

Python 到底装在哪？

Python 有两种常见安装方式。第一种是直接去 Python 官网下载并安装：https://www.python.org/。第二种是装 Miniconda，它本身也会带一套 Python。

两种方式都能用，选一个就可以。新手我更建议先走 Miniconda，后面做环境隔离会省很多麻烦。

再强调一次最容易误会的点：VS Code 里装了 Python 插件，不代表电脑里装了 Python。

怎么确认 Python 真的装好了

装完后你可以先做这个最小检查：

python --version      # 查看 Python 版本
where python          # 查看 python 执行路径

正常你会看到类似：Python 3.11.x，以及一条指向 Miniconda 目录的 python.exe 路径。

如果 python --version 没反应或提示找不到，通常是 PATH 没生效，或者终端还没刷新；如果 where python 指向了非 Miniconda 路径，多半是系统里有多套 Python 或 PATH 顺序靠前的不是你想用的那套。

改完 PATH 之后，记得把终端全关掉再开一次。

如果能看到版本号和明确路径，基本就说明本体已经可用了。看不到也别慌，很多时候只是环境变量或终端会话没刷新，关掉终端再开一次通常就能确认。

使用清华镜像加速（强烈建议国内用户配置）

清华开源镜像站：https://mirrors.tuna.tsinghua.edu.cn/。你可以把“清华源”理解成官方仓库在国内的同步副本，所以叫镜像。它不是魔改版，内容来源还是官方，只是访问路径换成了更稳定的国内节点。

如果你在国内装过 pandas、numpy，大概率见过“命令敲了很久没动静”的时刻。很多时候不是你写错了，而是默认源连接不稳定。把源切到镜像后，下载过程通常会顺很多。

想自己确认路径也不难：打开镜像站首页，搜 anaconda，进入目录就能看到常见通道。pkgs/main 是常用基础包，pkgs/free 偏历史包，cloud/conda-forge 对应社区维护、更新更快的 conda-forge。

channel 可以理解成 conda 查找包时依次访问的仓库列表。以下命令请在 Miniconda Prompt 中执行，而不是普通 CMD：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/         # 添加主仓库镜像（常用基础包）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/         # 添加历史仓库镜像（兼容旧依赖）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ # 添加 conda-forge 镜像（社区包更全）
conda config --set show_channel_urls yes                                                      # 显示包来源通道，排错时更容易定位

pip 默认访问官方 PyPI，国内网络下也可能慢。设置 index-url 后会长期生效：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple  # 设置 pip 默认镜像（持久生效）
pip config list                                                            # 查看配置是否生效

如果后面要回退到默认源，执行：

pip config unset global.index-url  # 取消自定义镜像，恢复默认 PyPI

3.6 Miniconda 安装与验证闭环

这一段我按“国内下载”和“国际下载”分开写，你照着走就能闭环。

国内用户（清华镜像）下载流程

打开 https://mirrors.tuna.tsinghua.edu.cn/。
进入首页后，看右侧的“下载链接”模块。
点击蓝色按钮“获取下载链接”。
在弹窗里切到“应用软件（或应用程序）”选项卡，左侧选择 Conda，右侧选择 Miniconda3-latest (Windows/x86_64, exe)。
x86_64 就是 64 位 Windows，大多数电脑都是这个；不要选 Linux 的 .sh，也不要选 macOS 的 .pkg。
下载后的文件名通常类似：Miniconda3-latest-Windows-x86_64.exe，看到这种格式基本就是对的。
下载 .exe 安装包到英文目录（比如 Downloads）。

国际用户（官网）下载流程

打开 https://docs.conda.io/en/latest/miniconda.html。
找到 Windows 64-bit Installer。
下载对应的 .exe 安装包。

Windows 用户可跳过这一小段：
Mac 用户也可以在同一页面下载 macOS 版本（Apple Silicon / Intel 按机型选）。
安装完成后在 Terminal 里先执行 conda --version 做最小验证。

下载好之后，安装步骤按这个走：

双击安装包。
用户范围建议选 Just Me（个人电脑更省心，也不容易碰权限问题）。
安装路径建议用 C:\Miniconda3，尽量避免中文路径和空格。
Add Miniconda to PATH：如果你是第一次安装，建议勾选，这样可以直接在 CMD 中使用 python 和 conda；如果后面要管理多个 Python 版本，再学习更规范的环境隔离方式。
Register Miniconda as default Python 建议勾选，这样常见工具会优先识别这套 Python；如果你已经有固定项目绑定其他 Python，再按实际情况决定。
安装完成后，在开始菜单搜索并打开 Miniconda Prompt。

如果你不想改系统 PATH，也可以不勾选；但新手为了少踩坑，勾上更省事。后面我也会教你怎么验证和手动处理。 装完立刻验证

安装完成后，先在 Miniconda Prompt 里跑一遍这三条：

conda --version              # 确认 conda 可用
python --version             # 确认 Python 可用（来自 Miniconda）
where python                 # 确认 python 路径指向 Miniconda 目录

conda --version 正常会显示类似：conda 24.x.x
python --version 正常会显示类似：Python 3.11.x
where python 第一条路径通常应指向：C:\Miniconda3\python.exe（或你自己的 Miniconda 安装目录）
where python 有时会输出多行，第一行就是当前优先命中的 Python。

3.7 PATH 环境变量：不勾选时怎么手动处理

这个步骤听起来有点“系统设置味”，但实际做一遍就熟了。你可以按下面这条路走：

右键桌面或资源管理器里的“此电脑”。
点击“属性”。
点击“高级系统设置”。
在弹出的窗口里点击“环境变量”。
在“系统变量”区域找到 Path。
点击“编辑”。
点击“新建”。
添加 Miniconda 安装目录，例如 C:\Miniconda3。
再点击一次“新建”，添加 C:\Miniconda3\Scripts。
一路点击“确定”保存。
关闭所有已经打开的终端窗口，再重新打开。

你可以把 PATH 理解成系统查找可执行文件的“目录列表”。你在 cmd 里输入 python，系统就会按这张列表从上到下去找 python.exe。如果目录没加进去，命令行就会表现成“找不到 python”。

至于为什么要“关掉终端再开”，原因也不复杂：终端启动时会读取一份当时的环境变量快照。你后面改了 PATH，老窗口不会自动刷新，新开的窗口才会拿到最新配置。

怎么验证 PATH 已经生效

配完后建议马上检查一次：

where python   # 查看 python 实际命中路径
echo %PATH%    # 打印当前 PATH 列表，确认是否包含 Miniconda 目录

如果 where python 能看到你刚配置的路径，基本就说明已经生效了。

3.8 创建 learn 环境与常见坑

在 Miniconda Prompt 里执行：

conda create -n learn python=3.11  # 创建名为 learn 的 Python 3.11 环境
conda activate learn               # 激活 learn 环境
python --version                   # 检查当前 Python 版本
pip install requests               # 在当前环境安装 requests 包
conda deactivate                   # 退出当前环境

conda activate learn 成功后，提示符左侧通常会出现 (learn)，这是最直观的激活信号。

第一次执行 conda create -n learn python=3.11 时，通常会看到：

Proceed ([y]/n)?

输入 y 然后回车继续即可。

如果 pip install requests 报超时或下载很慢，优先回到上面的清华镜像小节检查配置是否生效。

还有一个很常见的小坑：没激活环境就直接装包，包装到了 base 或系统环境里，后面切到别的环境运行时就会冒 ModuleNotFoundError。

跑通这一组命令，你就完成了第一个可用开发环境。

如果遇到这些情况：

python 不是内部或外部命令
这通常是 PATH 没配置好，或者你改完 PATH 后终端没重开。最短排查：where python，然后重开终端。
where python 指向了别的路径
说明系统里可能有多套 Python，当前命中的不是你想用的那套。最短修复：调整 PATH 顺序，或先明确用 C:\Miniconda3\python.exe。
conda 不是命令
你大概率没在 Miniconda Prompt 里执行。最短修复：先切到 Miniconda Prompt，再试一次。
ModuleNotFoundError
先确认 VS Code 解释器和当前环境一致，再在当前环境里执行 pip install。

你会踩的坑

最常见的几个问题你大概率都会遇到：python 不是内部或外部命令、电脑里装了多个 Python 但不知道当前到底调用了哪个、pip 把包装进了系统环境而不是项目环境。

很多新手都会经历这个阶段。你可能在终端里敲了 conda activate learn，结果像“没反应”一样，既不报错也没明显变化。这通常不是命令坏了，而是终端没加载 conda，或者你开的不是 Miniconda Prompt。

我当年也踩过这个坑。最后回头看，问题基本都在路径和环境没对齐。先用下面两个命令把现状看清楚：

conda info --envs  # 查看所有 conda 环境，以及当前激活环境
where python       # 查看当前 python 命令实际指向的可执行路径

conda info --envs 用来确认当前激活的是哪个环境；where python 用来确认当前调用的 python 路径。

如果你看着这些输出有点懵也正常，先确认两件事：
第一，你是不是在 learn 环境里；第二，where python 第一条路径是不是你预期的那一个。

4. 版本管理

4.1 为什么要做版本管理

你大概率见过这种场景：桌面里有 final.py、final_final.py、final_final_v3.py，过几天自己都分不清哪个能跑。版本管理的价值就在这里：它把每次改动记录成时间线，能回看、能回退、也方便协作。

Git 是什么（用一句话说清楚）

Git 就是一套本地版本控制工具，负责记录代码历史和变更。

4.2 Git 安装与基础配置（Windows 主线 + Mac 支线）

先打开 Git 官网：https://git-scm.com/。Windows 用户点 Download for Windows（或等价入口），下载完成后双击安装包（文件名通常类似 Git-2.xx.x-64-bit.exe）。

安装器里你会看到不少页面，下面按“新手最关键选项”走一遍：

License：直接 Next。
这页主要是许可说明，不需要额外改动。
Select Destination Location：建议默认。
如果你要改路径，尽量英文目录，例如 D:\Git 或 C:\Program Files\Git。
Select Components：大体默认即可，关键项看这几个。
Git Bash Here 建议勾选（右键能快速开 Bash）；Git GUI Here 可选；Git LFS 建议勾选；Associate .git* configuration files with the default text editor 建议保留；Associate .sh files to be run with Bash 可选；Add a Git Bash Profile to Windows Terminal 可选。
Start Menu Folder：默认 Next。
新手不用在这页折腾。
Choosing the default editor used by Git：
如果你已经装了 VS Code，推荐 Use Visual Studio Code as Git's default editor；没装就先保持默认也能继续，后面可以再改。
Adjusting the name of the initial branch in new repositories：
推荐选 Override the default branch name for new repositories 并填 main，和主流仓库默认值保持一致。
Adjusting your PATH environment：
新手推荐 Git from the command line and also from 3rd-party software，这样在 CMD / PowerShell / VS Code 终端都能直接用 git。
Choosing the SSH executable 与 Choosing HTTPS transport backend：
都保持默认就行（通常是 Use bundled OpenSSH / Use the OpenSSL library）。
Configuring the line ending conversions：
推荐 Checkout Windows-style, commit Unix-style line endings，跨平台时更不容易出现整文件换行变更。
Configuring the terminal emulator to use with Git Bash：
保持默认 Use MinTTY 即可；你平时在 VS Code 内置终端使用也不冲突。
Choosing the default behavior of 'git pull'、credential helper、extra/experimental options：
这几页先保持默认（Git Credential Manager 也建议保留），先把主流程跑通。

安装完成后，先把所有终端窗口关掉再打开。然后在 CMD（Win + R 输入 cmd）里执行：

git --version    # 正常会看到：git version 2.xx.x

如果提示 git 不是命令，先重开一次终端；还不行就重装一遍，并确认 PATH 那页选的是“from the command line and also from 3rd-party software”。

Mac 支线（Windows 用户可跳过）：在 Terminal 输入 git --version，通常会提示安装命令行工具，按向导完成即可。装完后重开 Terminal 再执行一次确认。

第一次 Git 基础配置（user.name / user.email）

这一步是给提交记录写“署名信息”，不是账号密码。只要配置一次，后面提交会稳定很多。

git config --global user.name "你的名字"          # 设置提交显示名
git config --global user.email "you@example.com" # 设置提交邮箱
git config --global --list                        # 验证配置

你大概率会看到 user.name= 和 user.email= 这两行，说明配置已经生效。

4.3 GitHub 注册与账号准备

Git 是本地版本工具，GitHub 是远程托管与协作平台。一个负责记录版本，一个负责把版本放到线上并支持协作。

GitHub 官网：https://github.com/。

对初学者来说，GitHub 最大的意义是“学习过程可见”。你做过哪些项目、怎么改进，都会留下记录；别人能看，你自己也能回看。它还很适合学习他人的仓库结构、README 写法和 issue 提问方式，长期看非常实用。

4.4 GitHub 网页端入门：界面、建仓库、第一次提交

GitHub 默认是英文界面，这很正常，别紧张。新手先把常见按钮认熟，后面会越来越顺。
登录 https://github.com/ 后，你通常会到 Dashboard / Home。

你大概率会先看到三个东西：顶部搜索框、右上角头像和 + 菜单、左侧仓库区域。界面偶尔会小改，但核心入口基本不变：头像、+、Repositories、Settings。

先认这几个区域就够用：

左侧仓库区（Top repositories / Repositories）：看你常用仓库入口。
中间 Feed：先知道有这块就行，不用深挖。
右上角 + 菜单：最常用是 New repository。
Dashboard 左侧绿色 New：也能直接创建仓库。

再看右上角头像菜单，点开后常用项是：

Your profile / Profile：看个人主页。
Your repositories / Repositories：看自己的仓库列表。
Settings：账号设置（邮箱、密码、安全项都在这里）。
Sign out：退出登录。

第一次先把这几个入口认熟，就够你开始做项目了。

GitHub 注册（一步一步来）

GitHub 基本是英文界面。我不建议一上来就完全依赖翻译器，但你真的卡住时可以临时用一下，先把流程走通。后面慢慢养成“看英文按钮、看英文报错”的习惯就好。

注册流程按页面走：

打开 https://github.com/，右上角点 Sign up。
按顺序填写 Email address、Password、Username。
按提示完成 Verify your account（人机验证）和邮箱验证码。
完成后进入首页，通常会看到右上角头像或 + 菜单。

常见卡点：

Username 被占用：换一个名字。
邮箱收不到验证：先看垃圾箱，稍等几分钟，不行换邮箱。
页面加载慢：先刷新或稍后再试；如果经常卡加载，后面有可选方案。

GitHub 注册邮箱建议

国内用户用 QQ 邮箱、163 邮箱都可以。
如果你更习惯国际服务，Gmail、Outlook 也不错。
邮箱没有高下之分，能长期稳定使用、能收验证码、你自己顺手最重要。
同样地，英文界面也不用焦虑，先把常见按钮认熟；实在卡住再临时翻译一下即可。

网页端新建一个仓库（一步一步来）

Step 0：先确认你已登录成功。
你应该在右上角看到头像，这是后面操作的起点。

Step 1：进入创建页。
入口 1：右上角 + -> New repository；入口 2：Dashboard 左侧绿色 New。
你应该会进入 Create a new repository 页面。

Step 2：填写 Repository name。
建议用英文和短横线，比如 project-hello。
名称合法时通常会出现绿色通过提示；如果报错就改短一点、只用字母数字短横线。

Step 3：决定 Public / Private。
Public 更适合学习展示，别人能直接看；Private 更像个人草稿本。
你应该看到被选中的那一项高亮。

Step 4：Add a README file 建议勾选。
原因很实际：不空仓库，创建后直接能看到一个可读入口，结构更好理解。
勾选后创建页会显示该选项已启用。

Step 5：.gitignore 与 License。
.gitignore 可以先不选；如果你明确是 Python 项目，也可以选 Python 模板。
Choose a license 不懂就先不选，后面随时可补。

Step 6：点 Create repository。
创建后会进入仓库页面，默认在 Code 标签；如果你勾选了 README，会看到 README.md 出现在文件列表。

常见坑：

仓库名重复或不合法：换一个名字（字母/数字/短横线最稳）。
邮箱未验证：部分功能会受限，先去邮箱完成验证再回来。
页面加载慢：如果经常卡在创建页或加载页，再看后面的可选方案。

网页端做第一次提交（不装任何工具也能完成）

如果你现在还不想装任何工具，网页端也可以先跑通一次提交，先建立“我能把改动提交上去”的手感。

路线 1：Add file -> Create new file

进入仓库的 Code 页面，点 Add file -> Create new file。
文件名建议英文，比如 notes.md 或 hello.txt。
在编辑框写一点内容。
往下滚到 Commit changes，在 Commit message 填一句说明，比如 add notes。
点 Commit changes 提交。

你应该看到：新文件出现在列表里，Commits 计数会 +1。

路线 2：Add file -> Upload files

在 Code 页面点 Add file -> Upload files。
把本地的 main.py 拖进去（或点按钮选择文件）。
等上传进度完成后，往下到 Commit changes。
写 Commit message（例如 upload main.py），点 Commit changes。

你应该看到：main.py 出现在文件列表，提交历史新增一条记录。

网页端很适合这种小改动和临时补文件。长期开发还是更建议本地开发 + Desktop，效率会更稳。

仓库页面怎么读（Code 页面最常用区块）

第一次进仓库页，不用全看，先逛这几个区域：

顶部 Tab：Code / Issues / Pull requests / Actions / Settings。
新手先用 Code；Issues 用来提问题；Actions 后面再学。
Branch 下拉（通常是 main）：切分支入口。
绿色 Code 按钮：里面常用 HTTPS / SSH / Download ZIP。
Go to file：文件多的时候，快速跳到目标文件。
Add file：新增文件或上传文件入口。
文件列表（如 src/、README.md）：项目内容主入口。
页面下方会渲染 README，这是项目说明的第一入口。
Commits：改动历史入口，能看到时间线和每次提交内容。

4.5 Git 工作流与最小词汇

先记这五个词：commit、push、pull、branch、merge。日常就是本地改完先 commit，再 push；需要同步时 pull；并行开发用 branch，最后 merge。遇到冲突别慌，先看清两边改动再决定保留哪部分。

VS Code 里的 Git 功能（简版）

VS Code 左侧 Source Control（源代码管理）面板可以看 diff、暂存文件、写 commit message、提交。日常小改动很顺手。

但对新手来说，push/publish 阶段用 GitHub Desktop 往往更稳，状态也更直观。先用 GUI 跑通 commit/push/pull，命令行后面再补不迟。

4.6 国内访问慢时的可选处理

国内网络环境下，GitHub 偶尔会出现加载慢、登录慢、Release 下载慢。先用不依赖工具的方式：换时间段、优先用 GitHub Desktop 完成同步。

如果你经常卡在注册验证页、登录页，或者 Desktop 的网页授权回调慢，再考虑下面这个可选方案。

如果你需要可选的网络优化工具，可以了解 Watt 工具箱（Steam++）：https://steampp.net/。这里只是提供一个备选思路，不做效果承诺。工具只是手段，不要为了工具偏离学习目标。

4.7 GitHub Desktop 工作流：登录授权到 Publish

GitHub Desktop 下载地址：https://desktop.github.com/。

先把第一次登录/授权走完，后面步骤会顺很多：

打开 GitHub Desktop。
Windows 一般在 File -> Options -> Accounts，macOS 一般在 GitHub Desktop -> Settings -> Accounts。
点 Sign in，按提示打开浏览器授权（通常会看到 Authorize GitHub Desktop 或类似按钮）。
授权完成后回到 Desktop，应该能看到已登录账号（头像或用户名）。
如果网页授权加载慢，先换时间段或重试一次；还是经常卡再看上面的可选方案。

你应该看到的结果是：左上角 File 菜单可用；完成一次 commit 后，Publish repository 会出现。

确保你已经在 Desktop 里登录了 GitHub 账号（上一步做过）。

在桌面新建项目文件夹 project-hello。
用 VS Code 打开它，创建 main.py，写一行：print("Hello from my first repo")。
打开 GitHub Desktop：
- 如果本地还不是仓库，用 File -> New repository...。
- 如果已经是仓库，用 File -> Add local repository...。
在左下角填 Summary，点击 Commit to main。
点击 Publish repository。
回到 GitHub 网页确认仓库已创建，并能看到 main.py。

每一步你应该看到的状态：

新建仓库后，左侧会显示文件改动。
Commit 后改动列表会清空。
Publish 后网页仓库可访问。

如果你卡住了：

Commit 按钮是灰色：通常是没有保存文件或没有改动。
Publish 没出现：先确认是否已经登录 GitHub。
网页打不开或加载慢：先用 Desktop 完成流程；必要时再考虑上面的可选工具。

最小 Git 词汇表

repo 是仓库，commit 是快照，branch 是并行开发线，merge 是合并分支，push/pull 是和远端同步，clone 是把远端仓库拉到本地。

5. AI 时代你可以不写代码，但不能没有工程思维

AI 让写代码更快了，这件事没问题。真正没变的是：项目要落地，还是要有人把问题拆清楚、把结果做扎实。

我现在更在意的不是你记了多少语法，而是你能不能把一件事从“看起来会”变成“稳定可复现”。工程能力就在这个过程里。

真实场景通常很朴素。你复制一段代码，一跑就报 ModuleNotFoundError。先查解释器，where python 看路径，再把依赖装到当前环境。继续跑，又遇到 FileNotFoundError，再回头看路径。问题是一层层剥开的，不是一次性被“神答案”解决的。

我最想保留这句话：“你不理解的代码，AI 写得再漂亮也是负债。”

AI 能做很多事：给模板、给思路、解释报错、提优化建议。它做不了的，是替你理解需求、替你承担后果、替你做长期架构取舍。

工具选择也不用神化。初学者用豆包、DeepSeek 完全够起步；如果你对质量和上下文有更高要求，再试试 ChatGPT、Gemini、Claude。

在 VS Code 里配 Codex 这类插件也很实用，补全和解释都能提速。它可以当副驾驶，但方向盘还是你自己握着。

最后就收在一句话：你真正要练的，是把混乱变清晰。工具会换，方法会变，方向盘始终在你手里。

我希望你能掌握一种这个时代值得掌握的能力，发现问题与思考解决问题。当你遇到问题的第一反应不应该是放弃，而是我应该怎么去解决，大脑有一定概念了就去尝试。如果这个软件没有我还能去哪里获取下载资源？我现在做的东西有没有人也曾经和我遇到一样的问题？他们有没有留下解决方案？如果有我可以抄到答案吗？

成大事者不应该对工具的使用产生负担，工具只是你的手段，实现你的目的你不应该纠结你的手段够不够优雅完美。我一直很喜欢一句话：“真正的大师通常保持着一颗学徒的心”。我希望你在探索解决工程问题的时候，多多善用社区资源以及搜索引擎。这个世界很大，大到任何你生活中遇到的可能性或许已经被记录下来了。

6. 调试与工程习惯（可选进阶）

6.1 报错与定位：怎么读 Traceback，怎么缩小问题

新手怕报错很正常，我当年也会看到红字就紧张。后来才发现，报错更像导航：它在告诉你问题大概在哪。

先记住这四个问题：

我运行的到底是哪一个 Python/程序？先看 where python，再看 VS Code 解释器是不是同一个环境。
报错发生在哪一行？traceback 最后一段通常已经给了文件名和行号。
这行依赖什么外部东西？常见就是包、文件路径、权限、网络。
我改完怎么验证？做最小复现，一次只改一处再重跑。

ModuleNotFoundError: No module named 'xxx'
常见原因是缺包，或者包装到别的环境。
你可以这样做：先确认解释器；在当前环境装包；重跑同一段代码。
修好后你会看到：这个报错消失，程序继续执行。

FileNotFoundError: ...
多数是路径写错，或者启动目录不对。
你可以这样做：先确认当前工作目录；用绝对路径先跑通；再改回相对路径。
修好后你会看到：文件能被读取，后续逻辑开始跑。

SyntaxError
最常见的是少冒号、括号没闭合、缩进错。
你可以这样做：跳到报错行并看上一行；补符号并对齐缩进；重跑最小代码。
修好后你会看到：解释器不再第一时间中断。

6.2 断点调试：用 VS Code 看见变量与流程

打开要运行的 .py 文件。
在行号左侧点红点，设断点。
点左侧 Run and Debug，或按 F5。
第一次会让你选环境，选 Python；提示建 launch.json 就点确定。
程序停在断点后，看 Variables 面板里的变量值。
F10 单步，F11 进入函数，Shift+F11 跳出函数。

你应该看到：程序停在断点，变量区会刷新，你可以逐行观察。

total = 0
for i in range(1, 6):
    total += i
    if total >= 10:
        print("hit", total)
        break
print("done", total)

把断点打在 total += i 这行，你会看到 total 每轮怎么变化。调试不是炫技，是省时间。

6.3 工程习惯：目录结构、Markdown、文件类型、提交

project-hello/
  src/
  data/
  output/
  README.md
  .gitignore

src/ 放代码，data/ 放输入，output/ 放结果，README.md 讲怎么跑，.gitignore 管不该进仓库的文件。结构清楚后，排错会轻松很多。

路径和文件名尽量用英文，不是为了好看，而是减少跨工具时的奇怪兼容问题。

最小 README 可以先写这几行：

# project-hello
项目作用：xxx
运行方式：python src/main.py
依赖：xxx
输入在 data/，输出在 output/

你可以把 Markdown 理解成“纯文本 + 轻量标记”。它不是 Word 那种二进制格式，所以很适合放进 Git 做版本管理，也更容易跨平台打开。

工程里它出现频率很高：README、项目文档、issue 记录、博客、学习笔记，基本都能用它。你学会最小写法后，很多地方都能直接复用。

工具上，VS Code 直接就能写，建议装一个 Markdown 增强插件，比如 Markdown All in One。它的预览只是显示方式，不会改变你文件本身。
如果你更喜欢所见即所得，Typora 也很好用。我自己写长文时会用它，节奏会更顺。

最小写法先记这几个就够：

# 一级标题
## 二级标题
- 列表项
```python
print("hello")


链接写法我这篇文章里更推荐尖括号 `<https://...>`，统一、直观，拷贝后也不容易出格式问题。（`[text](url)` 也可用，看你习惯。）

你照抄就能用的迷你 README 模板：

```markdown
# project-hello
这个项目是做什么的
## 运行方式
python src/main.py
## 输入输出
输入在 data/，输出在 output/

常见坑就三个：列表缩进不一致、代码块三反引号没闭合、把中文标点写进代码里。中文标点对 Markdown 正文影响不大，但放进代码会直接出错。

先记高频就够用：.py/.md/.txt 是代码和文本，编辑器直接开；.json/.csv/.xlsx 是常见数据，前两者编辑器可读，表格类可用 Excel；.yaml/.yml/.toml 常做配置，改时注意缩进和键名；.zip/.7z 先解压再处理；.exe/.msi 是安装程序，不是数据文件。

扩展名不等于内容本质，但它能帮你快速判断该用什么工具。

习惯 1：小步提交，一件事一个 commit。
习惯 2：提交信息写人话，用 verb + object，比如 add notes、fix path。

你可能会遇到一次“改崩了”的时刻。那时如果历史里每条提交都清楚，你不会慌，回退也很快。这个习惯看起来小，真出事时最值钱。

7. 硬件常识：看懂你的电脑在做什么

7.1 硬件四件套：CPU、GPU、内存、存储

先把四个词分开，后面看配置就不会晕。CPU 像指挥中心，擅长通用计算和复杂逻辑分支，所以单线程表现常常很关键。GPU 更像一群小工人一起干活，擅长并行任务，比如图形渲染、深度学习里的矩阵计算。

RAM 是“工作台”，程序运行时的数据临时放这里；台面越大，同时摊开的东西越多。ROM 这个词在手机圈常被说成“存储”，但在 PC 语境里，大家口头说的“ROM/存储”通常是 SSD/HDD 这类持久化存储，不是严格意义的只读 ROM。

再补一层很实用的理解：RAM 是易失的临时空间。你开着程序时，变量和缓存都在这块“工作台”上；程序一退出、电脑一重启，或者直接断电，这些内容就会清空。你在断点调试里看到的变量值，本质也在 RAM 里，停掉进程后就没了。这也是为什么有时你重新打开程序，之前算到一半的中间结果会消失，它本来就没写进硬盘。

最常见误区就一句：内存（RAM）不等于硬盘（SSD/HDD）。一个管“运行时临时空间”，一个管“长期保存文件”，作用完全不同。

很多笔记本会同时出现核显和独显，这是正常设计。核显（iGPU）在 CPU 里，省电、发热低，写代码、看文档、日常开发都够用。独显（dGPU）是单独芯片，图形和并行计算更强，适合游戏、3D 渲染、视频导出、模型训练。

你会看到“自动切换”，本质是系统在做省电和性能平衡：轻任务走核显，重任务再调独显。对编程新手很实用的一点是，学编程本身不依赖独显；但如果你准备走深度学习，NVIDIA 的 CUDA 生态会更常见，没独显也能学，只是训练速度会慢不少。

7.2 存储与接口：HDD/SSD，SATA/M.2/NVMe

一句话先记住：HDD 和 SSD 都是“长期存东西”的地方，不是内存。HDD（机械硬盘）像老仓库，容量大、价格友好，但速度慢、会有噪音，也更怕震动；SSD（固态硬盘）像新仓库，快、安静、抗震，系统启动、装包、打开项目都会更利落。

新手最容易混的是三个词：外形、接口、协议。2.5 寸 SATA 常见为线缆连接；M.2 是小卡片形态；NVMe 是协议，通常跑在 PCIe 上。你会看到“长得像 M.2，但速度差很多”，多数就是协议不同，不是你看错。

装之前可以按三步看规格，不容易踩坑：

先看主板或笔记本规格页：确认支持 SATA 还是 M.2，别先买再猜。
再看细节：M.2 的长度规格（比如 2280）和插槽协议（SATA/NVMe）要对上。
最后看资源占用：有些 M.2 插槽会占用 SATA 通道；笔记本还要确认是否可扩展。

还有一个口语细节：很多人说“手机 256G 内存不够”，大多是在说存储空间快满了。你只要听懂对方在说“空间不够”就行，不必在术语上较劲。

7.3 内存条与频率：DDR4/DDR5 与速度指标

按“浏览器 + VS Code + Python + 表格”这种真实场景看，8GB 可以跑，但多开标签页后容易顶满；16GB 是现在最稳的甜点位，学习和中度开发都舒服；32GB 更像进阶余量，开虚拟机、数据处理、剪视频会更从容。

SSD 建议至少 512GB。原因很现实：开发环境、包缓存、项目文件、数据集都会慢慢吃空间，256GB 很快就紧张。看配置时别只盯 CPU，CPU 很强但内存很小，体验一样会被拖住。

DDR4 和 DDR5 本质是内存代际。它们不是随便混插的，能不能用由主板和 CPU 平台决定，所以先看兼容，再看参数。别把“新一代”理解成“所有机器都能直接升级”。

频率这块，商家有时写 MHz，有时写 MT/s，偶尔也会口语写成 Hz。你把它当“速度档位”理解就够了。频率高会有帮助，但体感不一定翻倍，因为瓶颈也可能在 CPU、磁盘，或者程序本身写得慢。

给新手一个可执行顺序：

先看兼容：主板和 CPU 支持 DDR4 还是 DDR5。
再看容量：先保证 16GB 起步，必要时上 32GB。
最后看频率：在预算允许时再抬一档，双通道（两条同规格）通常更稳。

真实开发里，浏览器 + VS Code + Python + 表格更容易先吃满容量，所以大多数时候“容量够不够”比“频率冲多高”更影响体验。

7.4 型号速读：Intel / AMD / NVIDIA

先说一个总原则：型号命名会随年份微调，后缀也会更新。遇到新后缀别硬猜，以官网说明为准。

Intel CPU 先看三件事：系列、代际、后缀。i3/i5/i7/i9 是大致定位，但同是 i7，12 代和 14 代差别可能很大。像 i5-12400、i7-13700K、i7-13620H、i5-1340P，先看前面的代数，再看后缀：K 常见为可超频，F 常见为无核显，笔记本里 H/HX 偏性能，U 偏低功耗，P 在中间档。

AMD CPU 也类似，先看 Ryzen 3/5/7/9 定位，再看代际数字。比如 Ryzen 5 5600、Ryzen 7 7700X、Ryzen 7 7840HS、Ryzen 5 7530U，数字大体反映代际和定位；笔记本后缀常见 H/HS/U。另外 APU（带较强核显）值得知道一下，轻度图形处理和轻剪辑会更舒服。

NVIDIA GPU 最容易看错的点是：数字大不一定更强，要先看“代”。GTX 多是更早一代，RTX 通常带更完整的新特性。比如 RTX 3060 和 RTX 4060，先分清代际，再看同代内 60/70/80/90 的定位；Ti/SUPER 一般是同代增强款。再提醒一句，Laptop GPU 同名不等于桌面版性能。做 AI 时，显存（VRAM）很关键，8GB 能入门，12GB 会宽松很多，16GB 以上在大模型和大图任务里更从容。

7.5 自查与远程：任务管理器、设备管理器、RDP、服务器

先看内存和硬盘：16GB RAM + 512GB SSD 作为起步更稳。
再看 CPU 的代际和定位：别只看 i7/i9 这几个字。
你要做 AI、游戏、渲染，再重点看独显；NVIDIA 生态通常更省事。
你更在意便携和续航，核显本也完全能学编程。
最后再看屏幕、接口、重量：学生党看便携，桌面党看扩展，按使用场景选。

你现在手里的电脑，大概率已经够你开始学习了，不用等一台“完美机器”才开工。

你前面学了 CPU、GPU、内存、硬盘这些概念，下一步就是在自己电脑里把它们对上号。入口不复杂，记住这三条路就够。

A) 任务管理器 -> 性能（最常用）

打开方式一：右键开始菜单，点“任务管理器”。
打开方式二：Win + R，输入 taskmgr 回车。
如果只看到简版窗口，先点“更多详细信息”。
进入“性能（Performance）”，依次点 CPU / 内存 / 磁盘 / GPU。
你会看到：CPU 名称与基础频率、内存总容量、磁盘型号与活动时间、GPU 名称与显存占用。

B) 设备管理器（看硬件列表与驱动状态）

打开方式一：Win + X 菜单，点“设备管理器”。
打开方式二：Win + R，输入 devmgmt.msc 回车。
展开 Display adapters / Processors / Disk drives / Network adapters。
你会看到设备名称列表；如果有异常，通常会有黄色感叹号。

C) 第三方工具：图吧工具箱（可选）

如果你想一眼看汇总信息，可以把它当补充工具。下载地址：https://www.tbtool.cn/。

打开方式一：浏览器直接访问上面的官网地址下载。
打开方式二：Win + R，直接输入 https://www.tbtool.cn/ 回车。
打开工具后看“硬件总览/传感器”一类页面，核对 CPU、内存、磁盘、GPU。
如果和任务管理器显示略有差异，先以系统入口为准，再交叉确认。

不同品牌电脑的显示项会有小差异，但入口基本一致：先看性能页，再看设备列表，最后用第三方做补充核对。

第一件事是会打开。三种方式任选一种：

Ctrl + Shift + Esc。
右键任务栏，点“任务管理器”。
Win + R 输入 taskmgr 回车。

第二件事是知道看哪几个标签页：

进程（Processes）：按 CPU/内存排序，找谁在吃资源。
性能（Performance）：看 CPU、内存、磁盘、GPU 的实时占用。
启动应用（Startup）：看开机自启项（不同版本可能显示为“启动”或“启动应用”）。

第三件事是会正确结束卡死程序：

先确认是你认识且卡住的程序（比如浏览器、编辑器）。
点选该进程。
点“结束任务（End task）”。
你应该看到程序窗口消失，CPU/内存占用回落。

补一条安全线：别随便结束你不认识的系统进程，比如 System、Service Host、Windows Explorer。不确定就先搜进程名或截图记录。进程本质上就是“正在运行的程序实例”。不确定是不是系统进程时，先别结束；把进程名复制去搜一下，通常 30 秒就能判断。

一个常见场景：电脑突然很卡，你先去“进程”按 CPU 排序，发现某程序长期 90% 以上。先保存手头工作，再结束它，通常就能把机器拉回可用状态。

它的作用不是“装驱动神器”，而是先帮你判断硬件状态对不对。

打开方式一：Win + X -> “设备管理器”。
打开方式二：Win + R 输入 devmgmt.msc 回车。
重点看四类：Display adapters（显卡）、Processors（CPU）、Disk drives（硬盘）、Network adapters（网卡）。
如果看到黄色感叹号：右键设备 -> Properties/属性 -> Device status/设备状态，先看系统给的原因。

更新驱动时的新手顺序也很简单：

先去硬件官网或整机厂商官网找对应型号驱动。
不要乱装来路不明的驱动包。
Windows 更新有时会带驱动，但可能不是最新版本。

如果你看到两个显卡（核显 + 独显），大多数情况下是正常现象，这和前面讲的自动切换逻辑是一致的。

一句话说清楚：远程桌面就是“把别的电脑当成你的电脑来用”，屏幕、键盘、鼠标都像在本地操作。
你会用到它的场景通常就这几类：远程到家里或公司的电脑拿文件、远程到实验室机器跑任务、远程到云服务器做部署和维护。

Windows 里最常见的连接步骤可以直接照做：

按 Win + R。
输入 mstsc，回车打开“远程桌面连接”。
在 Computer 里填目标机器的 IP 或机器名。
点 Show Options（可选）填用户名，避免每次重输。
点 Connect 开始连接。
输入密码，并按提示确认首次证书窗口。

你应该看到的是：屏幕会弹出一个新窗口，窗口里是另一台电脑的桌面，你可以像本地一样打开程序和文件。

常见坑先记四个：

对方电脑没开机或进了睡眠，连接会直接失败。
目标机没启用远程桌面，需要在“设置 -> 系统 -> 远程桌面”里打开允许远程连接。
网络不通时会超时，公网场景可能要内网穿透或端口转发。
账号权限不够也会被拒绝，而且不是所有 Windows 版本都适合当被远程主机。

安全上保持克制就行：别把密码到处保存，能用强密码就用强密码。

你可以把服务器理解成“24 小时开着的工作机器”。它优先考虑的是稳定、持续运行、可远程维护，而不是你坐在前面直接操作的体验。

新手最容易误解的一点是：服务器并不神秘，它本质上也是 CPU、内存、硬盘组成的一台电脑。区别主要在用途和运行方式。你的笔记本更像个人工作台，服务器更像长期值守的生产机。

很多服务器没有显示器和键盘，不是它不能接，而是日常没必要。管理员通常通过 SSH 或 RDP 远程进去做配置、部署、看日志。

把流程串起来你就很清楚了：你在本机写代码 -> push 到 GitHub -> 部署到服务器，本质就是把程序从“你的开发电脑”搬到“另一台长期运行的机器”。

台式机的关键词是扩展性、散热和性价比。适合长期固定开发、多屏办公、后续慢慢升级配件。
笔记本强调便携，性能和续航是折中关系。适合学习、出门上课、移动办公。
手机多数是 ARM 平台，适合“使用服务”而不是“开发主力”。它更像辅助终端，可以配合远程控制或云服务。
工作站面向渲染、仿真、AI 这类专业负载，稳定性和扩展空间更重要。别被“工作站”这个名字吓到，还是看你实际任务。
服务器核心是长期在线、远程管理、稳定运行。很多场景会用 Linux，而且常见无 GUI 或只保留最小图形环境。

给新手的判断框架，先按这个来就够：

先问自己：我是学习编程，还是已经有重度渲染/训练任务？
学习和日常项目优先保证可用性：16GB 内存 + 足够 SSD，通常比追极限型号更重要。
需要固定工位和多屏就偏台式机；经常移动就偏笔记本。
只有在任务明确需要时，再考虑工作站或服务器。
大多数情况下，你现在手里的电脑已经能开始做项目。

结语

如果你能把这篇文章从头到尾照着走一遍——哪怕只是跑通一次：装好环境、能在终端里跑起 python、能在 VS Code 里写一段循环、能在 GitHub 上创建仓库并成功提交——那你其实已经完成了“入门”的核心。

很多人以为编程入门是“背语法”，但我更愿意把它理解成一种生活化的能力：你能不能把一个问题拆开，找到资料，尝试验证，遇到报错不慌，最后把结果复现出来。你会发现，真正让人拉开差距的往往不是聪明，而是这套流程是否稳定。

最后还是那句话：工具只是手段。你用 Python、用 VS Code、用 GitHub，甚至用 AI 插件，都没问题。重点不是“我用了什么”，而是“我有没有把问题搞清楚，并且能把它做出来”。

为了让你不能有太大心里负担，我必须告诉你。本博客网站和你现在阅读的这篇文章我用了不少AI辅助，Chatgpt帮我写了不少，很好用。我为了节省了大量时间可以做别的事而高兴，很直观的提升了我的效率。

How to Get Started with Programming: Tools, Git, and Engineering Thinking

Tue, 17 Feb 2026 00:00:00 GMT

Preface

I’ve always believed this: people can’t imagine things outside what they already know. Even with AI this strong now, you still might not be able to build something you’re truly satisfied with just by prompting. And yes, you might feel anxious too. If AI is so powerful, does learning programming still matter? Won’t programmers be replaced anyway?

I know you have a lot of questions. In my view, times change and answers change every day. Rules that work today may not work tomorrow, and rules that work tomorrow may not work today either. Instead of staying in the dark, I’d rather you understand at least a bit of how things work. Nothing in this world is really that mystical. If possible, touch it with your own hands. I really like this line: “Practice is the only criterion for testing truth.”

Learning a skill is an honorable thing, and it can become a lifelong hobby. Whether you’re in middle school or just entered university, I think it’s worth learning how to use computers well, and even how to code and build projects.

I also think everyone has talent in some area. Sometimes it’s just not discovered yet because of environment or life experience. Maybe I walk past future geniuses every day and they don’t even know it. What I hope is that more students get sparked by one accidental moment when they’re young, then turn that spark into a real hobby.

As for me, I’m from Zhejiang. In high school we had a technical elective, and the information technology part was Python. Back then our school had an OJ problem site. Everyone loved occupying the computers to solve problems, and in free time we explored a lot of fun stuff. We didn’t realize it then, but that was the start of a different life path for many of us.

Whether you’re in engineering or the humanities, I still think it’s useful to understand these core ideas. When you make decisions later, I can’t guarantee you won’t feel confused. Sometimes knowing more actually gives you more confusion first. But then a big question mark appears in your mind, and you finally start thinking in a directed way.

1. What Is Programming

Programming is not as mysterious as it looks. It’s more like an engineering expression skill: break a problem down, arrange the steps, and let the machine execute them reliably.

You don’t need to understand every low-level detail at the beginning. Just remember one thing first: you’re not writing flashy syntax, you’re building a process that can be reproduced, debugged, and maintained.

1.1 Where Programming Sits in the Computer Stack

Think of it as a bottom-up chain. At the bottom is hardware: CPU, memory, and storage. The CPU also has its architecture (x86, ARM), which decides which instruction set the machine can understand.

Above that is the operating system (Windows / Linux / macOS). It manages the hardware and gives programs a unified interface. When your code touches files, network, or windows, the OS is what handles all that underneath.

Programming languages sit in the middle as a translation layer. You write Python or C, but the machine finally executes lower-level instructions. At the top are applications, like the browser or editor you click every day, or the small tools you build yourself.

What are Windows and Linux?

Windows and Linux are operating systems, not programming languages. You can think of them as managers: they allocate hardware resources and define execution rules.

I’ve seen many beginners confuse “I can use Windows” with “I can program.” That’s normal. An OS is more like the runtime environment. It decides how programs access files, request memory, and talk to devices.

The system is the stage, the program is the actor, and the language is how you write the script. Once you separate these roles, a lot of concepts stop mixing together.

1.2 Paths and Directories: Path, Root Directory, Relative Path

You can think of a path as an address and house number. When a program looks for a file, it’s really asking, “Where exactly is it?”

For example, C:\Users\Dan\Desktop\learning\hello.txt is a full address. When you use cd in a terminal, you’re walking to the right floor first, then picking up the file.

Here’s a very common pitfall: Chinese folder names are not always impossible, but with some toolchains, encoding settings, old libraries, or command-line combinations, non-ASCII paths can occasionally cause weird issues. To reduce random trouble, using English folder names is usually safer: short names like test, folder, project, data, output work great.

What is the root directory

In Windows, C:\ is a root. You can treat it like a top-level entry point, then beneath it you have user directories, project directories, and data directories. Long paths are just layers going down from this entry.

What is a relative path

A relative path is written relative to your current directory. An absolute path like C:\Users\Dan\Desktop\learning\hello.txt goes straight to the target. A relative path like .\hello.txt or data\input.txt starts from where you’re standing now.

The most common reason relative paths fail is not that the file doesn’t exist, but that you’re in the wrong directory. You think you’re in learning, but your terminal is still one level above.

Windows users can skip this short part:
On Mac, the root directory is /, and your home directory is usually /Users/your-username.
Relative path rules are the same, typically ./ and ../.

1.3 Architecture Differences: x86 vs ARM

x86 and ARM are two mainstream CPU architectures. You can treat them as two different machine dialects. Traditional PCs have long been mostly x86, phones and tablets are mostly ARM, and new Macs (Apple Silicon) are ARM too.

Your code is always translated into instructions the target architecture can execute. Over time you’ll notice: the same code on different devices can have compatibility differences. Often that’s not your coding mistake, just platform differences underneath.

Where programming languages fit in this system

This is where people mix things up most easily. Python is not an OS, and C is not a CPU. A language is a translation layer that organizes your ideas into something machines can run.

Once this position is clear, terms like “system error,” “interpreter version,” and “architecture compatibility” stop feeling like one tangled ball.

1.4 Core Programming Concepts: Flow, Script, Variables, Coding

A grounded example: batch-renaming images in your Downloads folder. First locate the target directory, then filter .jpg / .png, then define sorting and naming rules, and finally log failed items and retry.

You’ll notice what matters is process design, not how many syntax tricks you memorized. That’s algorithmic thinking. Language is a tool; process is the core.

What is a script?

A script is a small program for a specific task. The point is reducing repetitive work.

Things like organizing your Downloads folder, batch-renaming files, and auto-summarizing text are all script-friendly. It doesn’t have to be complex to be very practical.

What is a variable?

A variable is a name for data. Good names make code readable even days later; random names make code turn into riddles quickly.

If you’re counting images, image_count needs no explanation. If you call it a1, even you may have to guess what it means after three days. I made this mistake when I first wrote scripts: the code ran, but a month later I didn’t even want to touch it.

Variables look small, but they directly affect readability and your debugging speed later.

What is coding?

From another angle, coding is not a typing competition. It’s organization ability. You’re breaking an idea into executable structure: where variables go, how flow moves, how functions split, how modules are separated. Here, “coding” means writing code and turning ideas into programs, not character encodings like UTF-8.

If the structure is clear, future changes are easier. If the structure is messy, every new feature hurts. It’s normal if this still feels vague now. Start from one rule: write code that you yourself can understand later.

1.5 English and Reading Errors: Important, But Don’t Panic

Don’t turn this into an anxiety competition. You don’t need to memorize a whole dictionary before learning programming. I don’t suggest you pause coding to formally “start learning English first”; learn while doing.

But one thing is practical: sooner or later you’ll read English errors, English docs, and English issues. Whether you can extract key information directly affects your debugging speed.

So the goal is not “perfect English.” The goal is: understand core technical words, and understand your own variable names and error messages.

1.6 Common Beginner Mistakes and Mindset

I’ve seen many beginners get stuck in similar places: memorizing syntax without building anything, watching videos without hands-on practice, stopping at the first error, treating AI as magic without verification, or endlessly “preparing” without starting. And for AI specifically, asking it to build a whole website when you don’t know your own requirements is like becoming a vague client; the result often won’t match what you want.

These are usually rhythm problems, not ability problems. Build one tiny runnable result first, then add complexity step by step. Your mindset gets much steadier that way.

Pick the route first, then install tools

Many beginners get stuck on environment setup before writing a single line of code.

I recommend deciding direction first: pick Python as your first language, then run the minimum loop: “write -> run -> fix.”

Once you feel “it runs,” tool details become much easier to digest. Next I’ll talk about language choice first, then environment setup.

2. C or Python?

I’ll give you a stable recommendation here: learn Python first. Whether you’re from humanities, science/engineering, changing careers, or still in school, Python is usually the easiest way to build early positive feedback.

2.1 Why Start with Python

Python’s biggest advantage is fast feedback. You write a few lines and see a result immediately. That’s huge for beginners, because you keep getting the feeling that “I’m actually moving forward.” If you get timely positive feedback while learning, you’re more likely to stay interested and improve faster. I don’t want your first experience to be pure frustration from starting too hard.

Its syntax is also more intuitive, and its resources/community are mature. When you hit problems, there are usually workable answers. I’ve seen many beginners quit not because coding is impossible, but because they get no positive feedback for too long. Python is genuinely friendlier here.

2.2 Python in 10 Minutes (Up to Loops)

Let’s define scope first: this part only takes you up to loops, enough to run your first small program. Functions, lists, dicts, and file operations are intentionally not expanded here. You can verify this later after finishing environment setup, or skip to 2.4 for now.

Think of variables as “naming data.” Clear names make code easier to read.

name = "Dan"
age = 18
print(name, age)

After running, you should see one line like Dan 18.

print() outputs, input() takes input. input() returns a string, so convert with int() before numeric operations.

age = int(input("请输入你的年龄："))
print("明年你是", age + 1, "岁")

After running, enter a number and you’ll see “next year you are xx years old.”

if is conditional branching: only execute that branch when the condition is met.

score = 72
if score >= 60:
    print("及格")
else:
    print("再练练")

After running, you’ll see Pass (because the example score is 72).

for is commonly used for fixed-count repetition. range(5) is 0 to 4; range(1, 6) is 1 to 5.

for i in range(1, 6):
    print(i)

After running, it prints 1 through 5 line by line.

while is for “keep looping while condition is true.” For example, accumulate until reaching 100:

total = 0
n = 1
while total < 100:
    total += n
    n += 1
print(total, n - 1)

After running, it prints the accumulated result and the last added number (something like 105 14).

2.3 Self-Learning Entry and Mini Exercises

Once you can handle loops, you have enough to start. For functions, lists, dicts, files, and modules, learn them next by yourself. The core isn’t “memorize everything”; it’s learning to search, read docs, and verify outputs.

A good place to start is Runoob: https://www.runoob.com/. When you meet new syntax, don’t rush to memorize. Run a minimal example first and see exactly what it does.

Here’s one mini exercise. Get a working result first, then optimize gradually:

Narcissistic numbers (also called Armstrong numbers): for an n-digit number, the sum of each digit to the power of n equals the number itself. For 3-digit numbers, it means the sum of cubes of each digit equals the original number. I want you to find all narcissistic numbers in 100~999.
Hint: split into hundreds/tens/ones, cube each digit, compare with the original number.

2.4 Python Use Cases and Language Comparison

Its use cases are broad. In humanities, you can do text analysis, spreadsheet cleaning, and visualization. In economics/finance, common tasks include indicator calculations and report automation. In geography, you can process cloud maps and spatial data. On the science/engineering side, it’s great for experiment data cleaning, batch plotting, parameter scanning, and simple numerical computation. Move one step further and you’ll see it in automation scripts, web backends, AI preprocessing, and training scripts. You don’t need to master all of this at once. Build one small result in the scenario you care about most first; your learning speed will be much higher.

Python vs C: a minimal example

Same goal: print 1 to 5.

Python:

for i in range(1, 6):
    print(i)

#include <stdio.h>

int main() {
    for (int i = 1; i <= 5; i++) {
        printf("%d\n", i);
    }
    return 0;
}

This example isn’t to say one language is “more advanced.” It’s just to show entry friction differences directly.

2.5 Should You Learn C Later?

Should you learn it? Depends on your direction. Build programming intuition with Python first. If you later move into systems, performance, or low-level work, adding C becomes much smoother.

A minimal starter route

Learn Python basics first (variables, branching, loops, functions).
Build one runnable script (for example, batch rename).
When you hit errors, search, fix, and rerun.

Run this route once, and your foundation is stable.

3. Development Environment Setup

3.1 Editors and IDEs: Why Start with VS Code

If you’re just starting, I’d suggest Visual Studio Code first.

Let’s define IDE quickly. IDE (Integrated Development Environment) is like an all-in-one toolkit: editor, debugger, runner, project management, and so on. PyCharm and Visual Studio are typical IDEs.

I don’t recommend heavy IDEs on day one, not because they’re bad, but because too many features can distract you from the core question: “How does code actually run?” At the beginning, understanding that baseline flow matters more.

VS Code sits between a plain editor and a heavy IDE: lightweight by default, expandable when needed, enough without overload. That balance is very beginner-friendly.

The reasons are practical: cross-language support, mature extension ecosystem, usable integrated terminal, and handy Git integration. One unified toolchain means less mental load early on.

I got stuck during my first setup too. So many options on screen felt overwhelming. That’s normal. Get the toolchain running first; tune habits later.

Official site: https://code.visualstudio.com/.

Install the minimum set of extensions first; enough is enough:

Python (ms-python.python)
Pylance (ms-python.vscode-pylance)
Markdown All in One (yzhang.markdown-all-in-one)
GitLens (eamodio.gitlens, optional)

3.2 Python Extension and Interpreter: What VS Code Actually Does

This part confuses beginners easily. The Python and Pylance extensions mainly provide editor features: syntax highlighting, completion, jump-to-definition, type hints, debugging entry, etc.

They make writing smoother, but they are not the Python interpreter itself. The key sentence again: installing Python extension in VS Code does not mean Python is installed on your computer.

One layer deeper: VS Code is mostly your “write code and organize projects” workstation, not the runtime itself. It can call your system terminal, interpreter, and Git, but it does not install Python for you. Whether python runs in VS Code depends on whether your system has a usable interpreter and correct path config.

The Select Interpreter action in VS Code is basically telling the editor which Python on your machine this project should use.

Try this once directly: open VS Code, press Ctrl + Shift + P, type Python: Select Interpreter, then choose the learn environment you created. If you pick the wrong one, VS Code may run a different Python than the one you just installed.

After selecting correctly, the status bar usually shows the current Python environment/version (position may vary by theme). That’s the most direct success signal.

3.3 VS Code Installation, Chinese Language Pack, and Extensions

Start with the safest path. Don’t tweak too many options at first.

Go to the VS Code site and download the Windows installer.
You should see a clear Download for Windows button.
During installation, recommended options:
- Add to PATH
- Open with Code
- (optional) Register Code as an editor for supported file types
Launch VS Code after installation.
You should see the left activity bar (Explorer/Search/Source Control/Run/Extensions).
Open Extensions (the square icon), search and install the Simplified Chinese pack:
Chinese (Simplified) Language Pack for Visual Studio Code (official Microsoft pack).
Restart VS Code when prompted.
After restart, UI should switch to Chinese (if not, manually switch display language in Command Palette).
If you prefer Traditional Chinese, there’s also:
Chinese (Traditional) Language Pack for Visual Studio Code.
Do three things on first launch:
- Switch UI language to what you’re comfortable with.
- Install the minimal extension list above.
- Press Ctrl + ~ to open terminal and confirm commands can be entered normally.

Windows users can skip this short part:
VS Code also provides a macOS build at https://code.visualstudio.com/.
After install, open it directly; extension logic and interpreter selection are basically the same as on Windows.

What is a development environment?

Think of it as your programming workbench. The editor is for writing code, interpreter/compiler turns code into runnable behavior, and terminal is where you run commands and execute programs.

Package managers (like pip, conda) install and manage dependencies, while runtime defines what conditions your code runs under. You don’t need to master everything at once; it’s enough to know these parts work together.

3.4 Terminal and Win+R: Get Command Line Running First

What are CMD, PowerShell, and VS Code terminal exactly?

At first the black window may feel scary, but it’s just a place to type commands.

They’re all command-line entry points. CMD is simpler and easier to start with. PowerShell is more powerful. VS Code Terminal is basically one of these embedded in your editor so you switch fewer windows.

Pick one first. I suggest CMD.

Memorize a few core commands first: cd to change directory, dir to list files, mkdir to create directory, rmdir to remove empty directory, echo to output text, cls to clear screen.

Try this 3-minute exercise (copy-paste ready):

mkdir "%USERPROFILE%\Desktop\learning"  # 创建 learning 文件夹
cd /d "%USERPROFILE%\Desktop\learning"  # 进入 learning 文件夹（/d 支持切换盘符）
echo Hello Programming > hello.txt      # 创建并写入 hello.txt
dir                                     # 查看当前目录内容
type hello.txt                          # 查看文件内容
mkdir temp                              # 创建 temp 子文件夹
rmdir temp                              # 删除空的 temp 子文件夹
cls                                     # 清空终端屏幕

You will most likely see: after dir, hello.txt appears in the list; after type hello.txt, output is Hello Programming.

Two common pitfalls: forgetting cd /d so drive letter doesn’t switch; or creating files before entering learning, so files appear elsewhere.

If you understand what each command does, you’ve cleared the first terminal hurdle.

How to open system command line (Win + R)

If you’re not inside VS Code, open system command line directly: press Win + R, type cmd, press Enter.

After opening, you’ll usually see a prompt like C:\Users\your-username>. That’s your current directory.

If you accidentally open PowerShell, no need to panic. Most basic commands still work. Getting the workflow running matters most.

The terminal at the bottom of VS Code is essentially the same command-line environment embedded in the editor. Many commands follow the exact same logic.

Mac users can skip this Windows part:
On Mac, open Terminal (search Terminal with Spotlight).
Most commands are similar; Windows commonly uses cmd, Mac commonly uses bash/zsh.

3.5 Python Runtime, Miniconda, and Installation Route

I recommend Miniconda. Maybe Anaconda can be better in some cases, but I still hope you get familiar with terminal operations.

I still recommend Miniconda because it’s lightweight, controllable, and great for environment isolation.

Miniconda official download page: https://docs.conda.io/en/latest/miniconda.html.

Remember three words first: Python version (e.g. 3.10, 3.11), packages (third-party libraries like requests), and virtual environment (each project uses its own dependencies without conflicts).

Where is Python actually installed?

There are two common ways to install Python. One is direct install from the official Python site: https://www.python.org/. The other is installing Miniconda, which also includes its own Python.

Both ways work. Pick one. For beginners, I recommend starting with Miniconda to save trouble when you isolate environments later.

One more time for the most common misunderstanding: installing Python extension in VS Code does not mean Python is installed on your computer.

How to confirm Python is really installed

After installation, run this minimum check first:

python --version      # 查看 Python 版本
where python          # 查看 python 执行路径

Normally you’ll see something like Python 3.11.x, plus a python.exe path pointing to your Miniconda directory.

If python --version doesn’t respond or says command not found, PATH is usually not effective yet, or terminal session wasn’t refreshed. If where python points to a non-Miniconda path, you likely have multiple Python installs or PATH order is pointing to a different one first.

After changing PATH, remember to close all terminal windows and reopen.

If you can see both version and clear path, your runtime is basically ready. If not, don’t panic. Most of the time it’s just environment variables or terminal session not refreshed.

Use Tsinghua Mirror for Acceleration (Strongly recommended for users in mainland China)

Tsinghua open-source mirror: https://mirrors.tuna.tsinghua.edu.cn/. You can think of the “Tsinghua source” as a synchronized domestic mirror of official repositories. It’s not a modified fork; content still comes from upstream, just via a more stable local route.

If you’ve tried installing pandas or numpy in China, you’ve probably seen commands freeze for a long time. Often that’s not your code, just unstable default source connectivity. Switching to mirror usually makes downloads much smoother.

If you want to confirm paths yourself: open the mirror homepage, search anaconda, and you’ll find common channels. pkgs/main is core packages, pkgs/free is older compatibility packages, cloud/conda-forge is community-maintained packages with faster updates.

A channel is basically the repository list conda checks in order when resolving packages. Run the following in Miniconda Prompt, not plain CMD:

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/         # 添加主仓库镜像（常用基础包）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/         # 添加历史仓库镜像（兼容旧依赖）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ # 添加 conda-forge 镜像（社区包更全）
conda config --set show_channel_urls yes                                                      # 显示包来源通道，排错时更容易定位

pip uses official PyPI by default, which can also be slow on some domestic networks. Setting index-url becomes persistent:

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple  # 设置 pip 默认镜像（持久生效）
pip config list                                                            # 查看配置是否生效

If you want to revert to default source later, run:

pip config unset global.index-url  # 取消自定义镜像，恢复默认 PyPI

3.6 Miniconda Installation and Verification Loop

I’ll split this into “domestic download” and “international download.” Follow it and you’ll close the loop.

Domestic users (Tsinghua mirror) download path

Open https://mirrors.tuna.tsinghua.edu.cn/.
On the homepage, look at the “download links” module on the right.
Click the blue button “Get download links”.
In the popup, switch to “Applications (or Application Software)” tab, select Conda on the left, then choose Miniconda3-latest (Windows/x86_64, exe) on the right.
x86_64 means 64-bit Windows, which is most computers; don’t select Linux .sh or macOS .pkg.
Downloaded filename usually looks like Miniconda3-latest-Windows-x86_64.exe; this format is normally correct.
Save the .exe installer to an English-path directory (like Downloads).

International users (official site) download path

Open https://docs.conda.io/en/latest/miniconda.html.
Find Windows 64-bit Installer.
Download the corresponding .exe installer.

Windows users can skip this short part:
Mac users can download macOS builds on the same page (choose Apple Silicon / Intel based on your device).
After installation, run conda --version in Terminal for a minimum verification.

After download, installation steps are:

Double-click installer.
For user scope, Just Me is recommended (less permission issues on personal machines).
Installation path recommendation: C:\Miniconda3; avoid Chinese path and spaces.
Add Miniconda to PATH: if this is your first install, checking it is recommended so python and conda work directly in CMD. If you later manage multiple Python versions, you can adopt stricter isolation workflows.
Register Miniconda as default Python is recommended, so common tools prioritize this Python. If your existing projects depend on another Python, decide based on your situation.
After installation, search Start Menu and open Miniconda Prompt.

If you don’t want to modify system PATH, you can leave it unchecked; but for beginners, checking it usually avoids more pitfalls. I’ll also show verification and manual handling below. Verify immediately after install

After installation, run these three commands in Miniconda Prompt:

conda --version              # 确认 conda 可用
python --version             # 确认 Python 可用（来自 Miniconda）
where python                 # 确认 python 路径指向 Miniconda 目录

conda --version should output something like conda 24.x.x
python --version should output something like Python 3.11.x
first path in where python usually should point to C:\Miniconda3\python.exe (or your own Miniconda directory)
where python may print multiple lines; the first line is the currently prioritized Python.

3.7 PATH Environment Variable: Manual Handling When You Don’t Check It

This sounds very “system settings” at first, but once you do it once, it becomes easy.

Right-click “This PC” on desktop or in Explorer.
Click “Properties”.
Click “Advanced system settings”.
In the popup, click “Environment Variables”.
In “System variables”, find Path.
Click “Edit”.
Click “New”.
Add your Miniconda directory, e.g. C:\Miniconda3.
Click “New” again and add C:\Miniconda3\Scripts.
Click “OK” all the way to save.
Close all opened terminals, then reopen.

You can think of PATH as the system’s “search directory list” for executables. When you type python in cmd, Windows checks this list top-to-bottom to find python.exe. If the directory isn’t listed, command line will say it can’t find Python.

Why reopen terminal? Because terminal reads an environment snapshot when it launches. If you change PATH later, old windows won’t auto-refresh; only new windows read the new values.

How to verify PATH is effective

After configuration, check immediately:

where python   # 查看 python 实际命中路径
echo %PATH%    # 打印当前 PATH 列表，确认是否包含 Miniconda 目录

If where python shows your newly configured path, it’s basically effective.

3.8 Create the `learn` Environment and Common Pitfalls

Run these in Miniconda Prompt:

conda create -n learn python=3.11  # 创建名为 learn 的 Python 3.11 环境
conda activate learn               # 激活 learn 环境
python --version                   # 检查当前 Python 版本
pip install requests               # 在当前环境安装 requests 包
conda deactivate                   # 退出当前环境

After conda activate learn, you’ll usually see (learn) on the left side of prompt. That’s the most direct activation signal.

When you run conda create -n learn python=3.11 for the first time, you’ll usually see:

Proceed ([y]/n)?

Type y and press Enter to continue.

If pip install requests times out or is very slow, go back to the Tsinghua mirror section above and check if mirror configuration is effective.

Another common pitfall: installing packages without activating target environment first. Then packages may go into base or system environment, and when you switch environment later you’ll get ModuleNotFoundError.

If this command set runs through, you’ve finished your first usable dev environment.

If you run into these cases:

python is not recognized as an internal or external command
Usually PATH is not configured correctly, or you didn’t reopen terminal after changing PATH. Fastest check: where python, then reopen terminal.
where python points somewhere else
You probably have multiple Python installs and current one is not the one you expect. Fastest fix: adjust PATH order, or explicitly use C:\Miniconda3\python.exe.
conda is not a command
You’re most likely not in Miniconda Prompt. Fastest fix: open Miniconda Prompt and run again.
ModuleNotFoundError
Confirm VS Code interpreter matches your active environment, then run pip install inside that same environment.

Pitfalls you’ll likely hit

Most common ones: python not recognized, multiple Python installs with unclear active one, or pip installing into system env instead of project env.

Many beginners go through this stage. You might run conda activate learn and feel like “nothing happened”. Usually command isn’t broken; either conda wasn’t loaded in this terminal, or you’re not using Miniconda Prompt.

I hit this too. Looking back, most issues came from path and environment not aligned. Use these two commands to make current state explicit:

conda info --envs  # 查看所有 conda 环境，以及当前激活环境
where python       # 查看当前 python 命令实际指向的可执行路径

conda info --envs confirms which environment is active; where python confirms which executable is actually called.

If output still looks confusing, that’s normal. Just confirm two things first:
(1) are you in learn environment, and (2) does first line of where python match the Python you intended.

4. Version Control

4.1 Why You Need Version Control

You’ve probably seen this: desktop full of final.py, final_final.py, final_final_v3.py, and a week later you can’t tell which one actually runs. That’s where version control matters: it records each change as a timeline, so you can review, rollback, and collaborate.

What is Git (one sentence)

Git is a local version control toolset that records code history and changes.

4.2 Git Installation and Basic Setup (Windows Mainline + Mac Side Note)

Start at Git official site: https://git-scm.com/. Windows users click Download for Windows (or equivalent), then run installer (filename usually like Git-2.xx.x-64-bit.exe).

Installer has many pages. Here’s the beginner-focused pass through key options:

License: click Next.
This page is just licensing text.
Select Destination Location: default is fine.
If changing path, prefer English path like D:\Git or C:\Program Files\Git.
Select Components: mostly default, focus on key options.
Git Bash Here recommended; Git GUI Here optional; Git LFS recommended; Associate .git* configuration files with the default text editor recommended; Associate .sh files to be run with Bash optional; Add a Git Bash Profile to Windows Terminal optional.
Start Menu Folder: default Next.
No need to tweak this page as a beginner.
Choosing the default editor used by Git:
If VS Code is installed, choose Use Visual Studio Code as Git's default editor; otherwise default is fine and can be changed later.
Adjusting the name of the initial branch in new repositories:
Recommended: Override the default branch name for new repositories and set to main.
Adjusting your PATH environment:
Beginner recommendation: Git from the command line and also from 3rd-party software, so git works in CMD/PowerShell/VS Code terminal.
Choosing the SSH executable and Choosing HTTPS transport backend:
Keep defaults (usually Use bundled OpenSSH / Use the OpenSSL library).
Configuring the line ending conversions:
Recommended: Checkout Windows-style, commit Unix-style line endings, to avoid full-file line ending diffs cross-platform.
Configuring the terminal emulator to use with Git Bash:
Keep default Use MinTTY; doesn’t conflict with daily use in VS Code terminal.
Choosing the default behavior of 'git pull', credential helper, extra/experimental options:
Keep defaults for now (Git Credential Manager should stay enabled).

After install, close all terminal windows and reopen. Then in CMD (Win + R, type cmd) run:

git --version    # 正常会看到：git version 2.xx.x

If it says git is not a command: reopen terminal once first; if still broken, reinstall and make sure PATH page selected “from the command line and also from 3rd-party software.”

Mac side note (Windows users can skip): run git --version in Terminal. It usually prompts to install command line tools. Follow wizard, then reopen Terminal and verify again.

First Git basic config (user.name / user.email)

This sets commit identity, not account password. Configure once and commit records become stable.

git config --global user.name "你的名字"          # 设置提交显示名
git config --global user.email "you@example.com" # 设置提交邮箱
git config --global --list                        # 验证配置

You should see user.name= and user.email= lines, meaning configuration is active.

4.3 GitHub Registration and Account Preparation

Git is local version control; GitHub is remote hosting and collaboration. One records versions locally, the other puts versions online and supports collaboration.

GitHub official site: https://github.com/.

For beginners, GitHub’s biggest value is making learning visible. What you built and how you improved are recorded. Others can see it, and you can review it yourself. It’s also great for learning repository structure, README style, and issue-writing patterns from others.

4.4 GitHub Web Quickstart: Interface, New Repo, First Commit

GitHub UI is English by default, which is normal. Don’t panic. As a beginner, recognize core buttons first and everything gets easier.
After logging into https://github.com/, you’ll usually land on Dashboard / Home.

You’ll usually see three things first: top search box, top-right avatar and + menu, and left-side repo area. UI may change slightly over time, but core entries are stable: avatar, +, Repositories, Settings.

These areas are enough to start:

Left repo area (Top repositories / Repositories): quick access to your repos.
Center feed: just know it exists for now.
Top-right + menu: most used item is New repository.
Green New button on left Dashboard: also creates a repo.

In avatar menu, common entries are:

Your profile / Profile: your personal page.
Your repositories / Repositories: your repo list.
Settings: account settings (email/password/security, etc.).
Sign out: sign out.

For your first time, knowing these entries is enough.

GitHub registration (step by step)

GitHub is mostly English UI. I don’t recommend relying entirely on translators from day one, but if you’re truly stuck, use translation temporarily and get through the flow first. Over time, build the habit of reading English buttons and errors directly.

Registration flow:

Open https://github.com/, click Sign up in top-right.
Fill Email address, Password, Username in order.
Complete Verify your account and email verification code.
After completion, you’ll enter homepage and usually see your avatar or + menu on top-right.

Common blockers:

Username already taken: choose another one.
Verification email not received: check spam, wait a few minutes, or switch mailbox.
Slow page loading: refresh or retry later; if it happens often, see optional section below.

Mailbox suggestions for GitHub registration

Domestic users can use QQ Mail or 163 Mail.
If you prefer international services, Gmail/Outlook are also fine.
There’s no hierarchy between mailbox providers. The important part is long-term stability, receiving verification codes, and your own convenience.
Same for English UI: don’t panic. Learn common buttons first; translate temporarily only when truly stuck.

Create a new repo on web (step by step)

Step 0: confirm login success.
You should see your avatar at top-right.

Step 1: enter creation page.
Entry A: top-right + -> New repository; Entry B: green New on left Dashboard.
You should arrive at Create a new repository page.

Step 2: fill Repository name.
Use English plus hyphen, e.g. project-hello.
When valid, you’ll usually get a green pass hint. If error appears, shorten name and keep to letters/numbers/hyphens.

Step 3: choose Public / Private.
Public is better for learning showcase; Private works as private draft notebook.
You should see your selected option highlighted.

Step 4: Add a README file is recommended.
Practical reason: non-empty repo, with an immediate readable entry point.
After checking it, the option should show enabled.

Step 5: .gitignore and License.
.gitignore can be skipped at first; if this is clearly a Python project, choose Python template.
If unsure about Choose a license, skip for now and add later.

Step 6: click Create repository.
After creation you’ll enter repo page on Code tab by default; if README was selected, you’ll see README.md in file list.

Common pitfalls:

Duplicate/invalid repo name: switch to a different one (letters/numbers/hyphens are safest).
Email not verified: some features may be restricted; verify email first.
Slow page loading: if creation/loading pages get stuck often, check optional handling section later.

First web commit (without installing any tools)

If you don’t want to install tools yet, web flow can still complete your first commit and build confidence that “I can submit changes.”

Route 1: Add file -> Create new file

Open repo Code page, click Add file -> Create new file.
Use English filename like notes.md or hello.txt.
Write some content in editor.
Scroll down to Commit changes, fill Commit message (for example add notes).
Click Commit changes.

You should see: new file appears in list, and Commits count increases by one.

Route 2: Add file -> Upload files

On Code page click Add file -> Upload files.
Drag local main.py in (or click button to choose file).
Wait upload to finish, then scroll to Commit changes.
Fill Commit message (e.g. upload main.py) and click Commit changes.

You should see: main.py appears in file list, and commit history has a new entry.

Web flow is great for small edits and temporary file updates. For long-term development, local workflow + Desktop is still more stable and efficient.

How to read a repo page (most-used parts on Code tab)

First time entering repo page, don’t read everything. Just walk through these areas:

Top tabs: Code / Issues / Pull requests / Actions / Settings.
Beginners can focus on Code first; Issues is for questions/bug reports; Actions can wait.
Branch dropdown (usually main): branch switch entry.
Green Code button: common options include HTTPS / SSH / Download ZIP.
Go to file: quick jump when repo has many files.
Add file: create/upload entry.
File list (src/, README.md, etc.): main project content.
README renders in lower page area: first project description entry.
Commits: change history timeline and per-commit details.

4.5 Git Workflow and Minimal Vocabulary

Start with five words: commit, push, pull, branch, merge. Daily flow is usually: change locally -> commit -> push; when syncing use pull; use branch for parallel work; merge with merge at the end. If conflicts happen, don’t panic, inspect both sides and decide what to keep.

Git in VS Code (short version)

The Source Control panel in VS Code can show diffs, stage files, write commit messages, and commit. Very handy for small daily edits.

But for beginners, using GitHub Desktop for push/publish is often more stable and more visual. Run through commit/push/pull with GUI first; command line can come later.

4.6 Optional Handling When Access Is Slow in Mainland China

Under domestic network conditions, GitHub may sometimes be slow in loading, login, or release downloads. Start with no-tool options first: try another time period, and prioritize sync via GitHub Desktop.

If you frequently get stuck on registration verification pages, login pages, or Desktop authorization callback, then consider this optional route.

If you need an optional network optimization tool, you can check Watt Toolkit (Steam++): https://steampp.net/. This is only a backup option, with no effect guarantees. Tools are just tools; don’t let them distract you from learning goals.

GitHub Desktop download: https://desktop.github.com/.

Do first-time sign-in/authorization once, then everything after becomes smoother:

Open GitHub Desktop.
On Windows usually go File -> Options -> Accounts; on macOS usually GitHub Desktop -> Settings -> Accounts.
Click Sign in, then follow browser authorization flow (you’ll usually see Authorize GitHub Desktop or similar).
After authorization, return to Desktop and confirm account is visible (avatar or username).
If authorization page loads slowly, retry at another time first; if it still frequently blocks, see optional section above.

Expected result: File menu is available, and after one commit, Publish repository will appear.

Make sure you’re already signed into GitHub in Desktop (done above).

Create a project folder project-hello on desktop.
Open it in VS Code, create main.py, and write: print("Hello from my first repo").
In GitHub Desktop:
- If local folder is not a repository, use File -> New repository....
- If it already is, use File -> Add local repository....
Fill Summary in lower-left, click Commit to main.
Click Publish repository.
Go back to GitHub web and confirm repo is created and main.py is visible.

State checks after each step:

After repo init/add, changed files appear on left list.
After commit, changes list becomes empty.
After publish, web repo is accessible.

If you get stuck:

Commit button is gray: usually file not saved or no changes made.
Publish doesn’t appear: check if you’re logged in.
Web page won’t open or loads very slowly: finish flow in Desktop first; consider optional tool above only if necessary.

Minimal Git vocabulary

repo means repository, commit is a snapshot, branch is a parallel line, merge combines branches, push/pull sync with remote, and clone copies remote repo to local.

5. In the AI Era, You Might Not Need to Write Every Line, But You Still Need Engineering Thinking

AI has made coding faster. That’s true. What hasn’t changed is this: to land projects, someone still has to clarify problems and make results reliable.

What I care about now isn’t how much syntax you memorized. It’s whether you can turn “looks like it works” into “stable and reproducible.” That’s where engineering ability lives.

Real scenarios are often plain. You copy a code snippet and immediately get ModuleNotFoundError. First check interpreter, then where python, then install dependencies into the current environment. Run again, now you get FileNotFoundError, then go back and check paths. Problems are peeled layer by layer, not solved by one magical answer.

The one sentence I want to keep is: “Code you don’t understand is still debt, even if AI wrote it beautifully.”

AI can do a lot: templates, ideas, error explanations, optimization suggestions. What it cannot do is understand your requirements for you, take responsibility for mistakes, or make long-term architecture tradeoffs for you.

No need to mythologize tool choices either. For beginners, Doubao and DeepSeek are fully enough to start. If you need stronger quality/context handling, then try ChatGPT, Gemini, or Claude.

Using Codex-like plugins in VS Code is also practical. Completion and explanations can speed you up. It can be a copilot, but you’re still holding the steering wheel.

I’ll end this part with one line: what you really need to train is turning chaos into clarity. Tools will change, methods will change, but the steering wheel stays in your hands.

I hope you can build one ability worth having in this era: finding problems and thinking through solutions. When you hit a problem, your first reaction shouldn’t be giving up, but asking “how can I solve this?” Once your brain has at least a rough map, go try. If this software isn’t available, where else can I get it? Has someone met the same issue before? Did they leave a solution? Can I learn from it?

People who do big things shouldn’t carry psychological burden about tools. Tools are means, not identity. If a tool helps you reach your goal, you don’t need to obsess over whether the method looks elegant enough. I really like this sentence: “Real masters usually keep an apprentice heart.” When solving engineering problems, use community resources and search engines well. The world is big enough that many problems you face have probably already been recorded somewhere.

6. Debugging and Engineering Habits (Optional Advanced)

6.1 Error Reading and Localization: How to Read Traceback and Narrow the Problem

It’s normal for beginners to fear errors. I used to get nervous seeing red text too. Later I realized errors are more like navigation: they tell you roughly where the problem is.

Keep these four questions in mind:

Which Python/program am I actually running? Check where python, then verify VS Code interpreter is the same environment.
Which line did the error happen on? The last part of traceback usually gives filename and line number.
What external dependency does this line rely on? Usually packages, file paths, permissions, or network.
How do I verify after fixing? Build a minimal repro and rerun after changing one thing at a time.

ModuleNotFoundError: No module named 'xxx'
Typical causes are missing package or package installed in wrong environment.
Do this: confirm interpreter, install package in current environment, rerun same code.
After fix you should see: this error disappears and execution continues.

FileNotFoundError: ...
Most commonly wrong path or wrong startup directory.
Do this: confirm current working directory, run with absolute path first, then switch back to relative path.
After fix you should see: file is read successfully and subsequent logic starts running.

SyntaxError
Most common causes are missing colon, unclosed bracket, or bad indentation.
Do this: jump to error line and inspect previous line, fix symbols and indentation, rerun minimal code.
After fix you should see: interpreter no longer exits immediately.

6.2 Breakpoint Debugging: Use VS Code to See Variables and Flow

Open the .py file you want to run.
Click left of line number to set a red breakpoint.
Click Run and Debug in sidebar, or press F5.
First run asks for environment; choose Python. If it asks to create launch.json, confirm.
When program pauses at breakpoint, inspect values in Variables panel.
F10 step over, F11 step into, Shift+F11 step out.

You should see: program paused at breakpoint, variables panel updating, and line-by-line execution control.

total = 0
for i in range(1, 6):
    total += i
    if total >= 10:
        print("hit", total)
        break
print("done", total)

Set breakpoint at total += i, and you’ll see how total changes each iteration. Debugging isn’t for show, it’s for saving time.

6.3 Engineering Habits: Directory Structure, Markdown, File Types, Commits

project-hello/
  src/
  data/
  output/
  README.md
  .gitignore

Put code in src/, input in data/, output in output/, usage notes in README.md, and non-tracked files in .gitignore. Once structure is clear, debugging gets much easier.

Try to use English paths and filenames, not for style points, but to reduce weird cross-tool compatibility issues.

A minimal README can start like this:

# project-hello
项目作用：xxx
运行方式：python src/main.py
依赖：xxx
输入在 data/，输出在 output/

You can think of Markdown as “plain text + lightweight markup.” It’s not a binary format like Word, so it’s great for Git version control and easy cross-platform opening.

It appears everywhere in engineering: README, project docs, issue records, blogs, study notes. Once you learn the minimal syntax, you can reuse it across many places.

Tool-wise, VS Code can edit it directly. A Markdown extension like Markdown All in One is recommended. Preview is only a display mode; it doesn’t change your file itself.
If you prefer WYSIWYG, Typora is also great. I use it for long writing; the flow feels smoother.

For minimal syntax, these are enough to remember:

# 一级标题
## 二级标题
- 列表项
```python
print("hello")


For links, this article prefers angle-bracket style `<https://...>`: consistent, direct, and less formatting trouble after copy. (`[text](url)` also works, choose what you prefer.)

Mini README template you can copy directly:

```markdown
# project-hello
这个项目是做什么的
## 运行方式
python src/main.py
## 输入输出
输入在 data/，输出在 output/

Three common pitfalls: inconsistent list indentation, unclosed triple backticks, and Chinese punctuation in code blocks. Chinese punctuation is usually fine in Markdown prose, but in code it often breaks execution.

High-frequency file types are enough at first: .py/.md/.txt are code/text and can be opened directly in editor; .json/.csv/.xlsx are common data formats, first two are editor-readable and table files can be opened in Excel; .yaml/.yml/.toml are common config formats, pay attention to indentation and keys; .zip/.7z should be extracted first; .exe/.msi are installers, not data files.

File extension doesn’t define everything, but it’s still a useful first signal for choosing the right tool.

Habit 1: small commits, one clear change per commit.
Habit 2: commit messages in plain language, use verb + object like add notes, fix path.

You’ll probably have a moment where something gets broken badly. If your commit history is clear, you won’t panic and rollback is fast. This habit looks small, but pays off when things go wrong.

7. Hardware Basics: Understand What Your Computer Is Doing

7.1 The Four Hardware Pieces: CPU, GPU, RAM, Storage

First separate these four terms, and configuration sheets become much easier to read. CPU is like the command center, good at general-purpose computation and complex branching, so single-thread performance is often important. GPU is more like many workers doing tasks together, great at parallel workloads like graphics rendering and matrix-heavy deep learning.

RAM is your “workbench,” where runtime data is kept temporarily. The bigger the bench, the more things you can spread out at once. In phone communities, ROM is often casually used to mean “storage,” but in PC context, what people call “ROM/storage” is usually persistent storage like SSD/HDD, not strict read-only ROM.

One more practical layer: RAM is volatile temporary space. While programs run, variables and caches stay on this workbench. Once program exits, computer restarts, or power is cut, this data is cleared. Values you see during breakpoint debugging are also runtime state in RAM, and they disappear when process stops. That’s why reopening a program often loses half-computed intermediate results unless they were written to disk.

Most common misconception in one sentence: memory (RAM) is not the same as storage (SSD/HDD). One is temporary runtime space, the other is long-term file storage.

Many laptops show both iGPU and dGPU, and that’s normal. Integrated GPU (iGPU) is inside CPU: power-saving, cooler, and enough for coding/docs/daily dev. Dedicated GPU (dGPU) is separate silicon: stronger for graphics and parallel compute, suitable for gaming, 3D rendering, video export, and model training.

Automatic switching is the system balancing power and performance: light tasks on iGPU, heavy tasks on dGPU. Practical note for beginners: learning programming itself doesn’t require a dGPU. But if you’re heading into deep learning, NVIDIA CUDA ecosystem is more common. You can still learn without dGPU; training is just slower.

7.2 Storage and Interfaces: HDD/SSD, SATA/M.2/NVMe

One sentence to remember first: both HDD and SSD are for long-term storage, not RAM. HDD is like an old warehouse: large capacity and cheaper, but slower, noisier, and more sensitive to shock. SSD is a modern warehouse: faster, quieter, and shock-resistant. Booting, package install, and opening projects all feel snappier.

Beginners most commonly mix up three things: form factor, interface, and protocol. 2.5-inch SATA is typically cable-connected; M.2 is the card-like form factor; NVMe is a protocol usually running on PCIe. If two drives look like M.2 but speed differs a lot, protocol differences are often the reason.

Before buying/installing, check specs in three steps to avoid pitfalls:

Check motherboard/laptop spec page first: confirm whether it supports SATA or M.2 before purchasing.
Check details: M.2 length (e.g. 2280) and slot protocol (SATA/NVMe) must match.
Check resource sharing: some M.2 slots may disable SATA channels; on laptops confirm expansion support first.

One language detail: when people say “my phone’s 256G memory is full,” they usually mean storage space is full. Just understand the meaning; no need to argue terminology.

7.3 RAM Sticks and Frequency: DDR4/DDR5 and Speed Indicators

In real scenarios like “browser + VS Code + Python + spreadsheets,” 8GB can run but fills up quickly with many tabs. 16GB is the current sweet spot for learning and moderate development. 32GB gives more headroom for VMs, data processing, and video editing.

For SSD, at least 512GB is usually more comfortable. Reason is practical: development environments, package caches, project files, and datasets keep growing. 256GB gets tight quickly. Don’t stare only at CPU; a strong CPU with tiny RAM still feels constrained.

DDR4 and DDR5 are memory generations. They are not freely mixable; compatibility depends on motherboard and CPU platform. Check compatibility first, then parameters. “Newer generation” doesn’t mean every machine can upgrade directly.

For frequency labels, vendors may use MHz, MT/s, or casually Hz. Treat it as speed tier. Higher frequency can help, but perceived performance won’t always double because bottlenecks may be CPU, disk, or program design itself.

A practical order for beginners:

Compatibility first: does motherboard/CPU support DDR4 or DDR5?
Capacity second: secure 16GB baseline, then 32GB if needed.
Frequency last: increase one tier if budget allows; dual-channel (two matching sticks) is usually more stable.

In real development, browser + VS Code + Python + spreadsheets usually hit capacity limits before extreme frequency limits, so capacity often impacts experience more.

7.4 Quick Model Reading: Intel / AMD / NVIDIA

One overall rule first: naming conventions change with each year, suffixes evolve too. If you see a new suffix, check official docs instead of guessing.

For Intel CPU, read three parts: series, generation, suffix. i3/i5/i7/i9 are broad positioning, but the same i7 across generations can differ a lot. In examples like i5-12400, i7-13700K, i7-13620H, i5-1340P, check generation first, then suffix: K often means unlocked overclocking, F often means no iGPU, laptop H/HX usually performance-focused, U low-power, P in-between.

AMD CPU is similar: start with Ryzen 3/5/7/9 positioning, then generation numbers. For models like Ryzen 5 5600, Ryzen 7 7700X, Ryzen 7 7840HS, Ryzen 5 7530U, numbers broadly represent generation and class; laptop suffixes often include H/HS/U. Also know APU (stronger integrated graphics) exists; it helps with light graphics and light editing tasks.

For NVIDIA GPU, the easiest mistake is this: bigger number isn’t always stronger unless you compare generation first. GTX is generally older generation, RTX usually includes newer feature sets. Example RTX 3060 vs RTX 4060: identify generation first, then compare 60/70/80/90 tiers within the same generation. Ti/SUPER are usually enhanced variants in that generation. Also remember Laptop GPU with same name is not equal to desktop performance. For AI, VRAM matters a lot: 8GB is entry level, 12GB is much more comfortable, and 16GB+ gives better room for larger models/images.

7.5 Self-check and Remote Use: Task Manager, Device Manager, RDP, Server

Check memory and storage first: 16GB RAM + 512GB SSD is a stable baseline.
Then check CPU generation and class: don’t judge by i7/i9 label alone.
Only if your tasks are AI/gaming/rendering, prioritize dGPU; NVIDIA ecosystem is often more convenient.
If portability and battery matter more, iGPU laptops can absolutely handle programming study.
Finally check display, ports, and weight based on your usage scenario.

Your current computer is very likely enough to start learning. No need to wait for a “perfect machine” to begin.

Now that you’ve learned CPU/GPU/memory/storage concepts, next step is mapping them on your own machine. It’s not complicated. Three entry paths are enough.

A) Task Manager -> Performance (most common)

Method A: right-click Start menu, open Task Manager.
Method B: Win + R, type taskmgr, press Enter.
If you only see simplified view, click “More details” first.
Go to Performance, then click CPU / Memory / Disk / GPU one by one.
You’ll see: CPU model and base speed, total memory capacity, disk model and active time, GPU name and VRAM usage.

B) Device Manager (hardware list and driver state)

Method A: Win + X menu -> Device Manager.
Method B: Win + R, type devmgmt.msc, press Enter.
Expand Display adapters / Processors / Disk drives / Network adapters.
You’ll see device name lists; yellow exclamation usually means abnormal status.

C) Third-party tool: TUZB Toolbox (optional)

If you want one-screen overview, use it as supplementary tool. Download: https://www.tbtool.cn/.

Method A: open browser and visit the official URL above.
Method B: Win + R, directly enter https://www.tbtool.cn/, press Enter.
After opening, check pages like hardware overview/sensors to compare CPU, memory, disk, and GPU.
If values differ slightly from Task Manager, trust system entries first and use third-party data as cross-check.

Display details vary by brand/device, but entry path is stable: check performance page first, then hardware list, then optional third-party cross-check.

First skill: open it. Three methods, pick one:

Ctrl + Shift + Esc.
Right-click taskbar -> Task Manager.
Win + R, type taskmgr, Enter.

Second skill: know which tabs to read:

Processes: sort by CPU/memory to find what’s consuming resources.
Performance: watch real-time CPU/memory/disk/GPU usage.
Startup: startup apps (name may vary slightly by Windows version).

Third skill: end frozen apps correctly:

Confirm it’s an app you recognize and it’s frozen (e.g. browser/editor).
Select the process.
Click End task.
You should see app window disappear and CPU/memory usage drop.

One safety line: don’t end unknown system processes casually, like System, Service Host, Windows Explorer. If unsure, search process name first or take a screenshot for record. A process is basically an “instance of a running program.” If you’re not sure whether it’s a system process, don’t end it first; copy process name and search it, you can usually judge in 30 seconds.

A common scene: PC suddenly becomes very laggy. Open Processes, sort by CPU, find one process staying above 90%. Save your current work first, then end that process. Usually this brings the machine back to usable.

Device Manager is not a “magic driver installer.” Its first value is helping you verify whether hardware state is normal.

Method A: Win + X -> Device Manager.
Method B: Win + R, type devmgmt.msc, press Enter.
Focus on four categories: Display adapters (GPU), Processors (CPU), Disk drives (storage), Network adapters (network card).
If you see a yellow exclamation mark: right-click device -> Properties -> Device status, read system-provided cause first.

Beginner-safe order for driver updates:

Get drivers from hardware vendor or laptop OEM official site first.
Avoid unknown third-party driver packages.
Windows Update may provide drivers too, but not always the latest.

If you see two GPUs (iGPU + dGPU), in most cases that’s normal and aligns with automatic switching logic discussed above.

One-sentence definition: remote desktop means “use another computer as if it were your own,” with display/keyboard/mouse behavior similar to local operation.
Typical use cases: connect to home/company PC for files, connect to lab machine for tasks, connect to cloud server for deployment and maintenance.

Most common Windows connection steps are straightforward:

Press Win + R.
Type mstsc, press Enter to open Remote Desktop Connection.
In Computer, enter target machine IP or hostname.
Click Show Options (optional) to fill username and avoid retyping.
Click Connect.
Enter password and confirm certificate prompt on first connection.

You should see: a new window pops up, showing the other machine’s desktop, where you can open apps/files like local.

Four common pitfalls:

Target machine is off or asleep: connection fails directly.
Remote Desktop not enabled on target: enable it in “Settings -> System -> Remote Desktop.”
Network unreachable causes timeout; in public network, port forwarding/tunneling may be needed.
Account permission insufficient can also deny access; not all Windows editions are suitable as remote host.

Security-wise, keep it simple: don’t store passwords everywhere, and use strong passwords whenever possible.

You can think of a server as a “24/7 working machine.” It prioritizes stability, continuous operation, and remote maintainability, not direct sitting-in-front interaction experience.

The easiest beginner misunderstanding: servers are not mysterious. At core they are still CPU + memory + storage computers. Difference is mainly usage and operation mode. Your laptop is a personal workstation; a server is a long-running production machine.

Many servers have no monitor/keyboard attached, not because they can’t, but because daily operations don’t need it. Admins typically use SSH or RDP for config, deployment, and logs.

Once you connect the full flow, it’s clear: write code locally -> push to GitHub -> deploy to server. You’re moving a program from your dev machine to another machine that runs continuously.

Desktop PC keywords are expandability, cooling, and cost efficiency. Great for fixed long-term development, multi-monitor setup, and gradual hardware upgrades.
Laptops emphasize portability, with a balance between performance and battery life. Suitable for study, classes, and mobile work.
Phones are mostly ARM-based and better for “using services” than as primary dev devices. They work well as auxiliary terminals via remote control/cloud services.
Workstations target professional loads like rendering, simulation, and AI, where stability and expansion matter more. Don’t be intimidated by the name; match it to your actual tasks.
Servers are about long uptime, remote administration, and stability. Many scenarios use Linux, often without GUI or with minimal graphical environment.

A practical decision framework for beginners:

Ask first: am I learning programming, or already doing heavy rendering/training tasks?
For study and daily projects, prioritize usability: 16GB RAM + enough SSD usually matters more than chasing top-tier model names.
If you need fixed desk and multi-monitor setup, lean desktop; if you move often, lean laptop.
Only consider workstation/server when your task clearly requires them.
In most cases, the computer you already have is enough to start building projects.

Conclusion

If you can follow this article once from start to finish — even just once — set up your environment, run python in terminal, write a loop in VS Code, create a repository on GitHub, and submit successfully, then you’ve already completed the core of “getting started.”

Many people think programming entry means “memorizing syntax,” but I prefer seeing it as a practical life skill: can you break down a problem, find references, verify attempts, stay calm with errors, and finally reproduce results? You’ll find that real gap usually comes not from raw cleverness, but from whether this workflow is stable.

One final line: tools are means. Using Python, VS Code, GitHub, or AI plugins is all fine. The key is not “what tool I used,” but “did I understand the problem clearly and build a working result.”

To reduce your psychological burden, I want to be direct: this blog site and this article were also heavily AI-assisted. ChatGPT helped me write a lot, and it worked very well. It saved me significant time that I could spend on other things, and it improved my efficiency in a very direct way.

How I Turned My Tablet into a Second Monitor with Sunshine

Mon, 16 Feb 2026 00:00:00 GMT

Preface

I have been using a laptop for both work and entertainment for years. Because I move between places a lot, I never bought a dedicated external monitor. Part of it was me being picky, and part of it was the classic “if I buy one, I probably need two” dilemma.

At some point, the single-screen setup just became annoying. Gaming felt cramped, coding felt cramped, everything felt cramped. I started regretting not buying a monitor earlier.

I only took this seriously after trying Apple Vision Pro and learning what Sunshine could do for low-latency streaming. I still did not want to overcomplicate things, but the idea stayed in my head.

My tablet is a Huawei MatePad 11, with a 2560x1600 panel, close enough to my laptop’s workflow needs. I tested 90Hz streaming at that resolution and saw around 6ms delay in the path I measured. In real use it felt smooth enough to be useful, not just “tech demo smooth.”

I do not use this setup every single day, but if you want a portable second screen without adding more cables to your desk, it is a very practical option.

What I Want from a Second-Screen Experience

I wanted a true extended screen, not a remote-control mirror. I did not want accidental touches on the tablet to mess with my main cursor. I wanted the tablet to sit on my left side and behave like a natural extension of my desktop space.

The ideal use case for me is simple: the main screen for active work, the side screen for docs, serial logs, dashboards, or reference windows. Since it is an actual extended display, dragging content across is fast and natural.

I also wanted it wireless. I like being able to pick up the tablet and move around when needed. A cable works, but for this use case it quickly becomes visual and practical clutter.

Solution Overview

One-line topology:

PC -> Sunshine (encoding) -> LAN -> Moonlight -> Tablet
            |
        Parsec-VDD (virtual display)

Role split:

Parsec-VDD: creates the second display target
Sunshine: captures and encodes that display
Moonlight: decodes and shows it on the tablet

Preparation

Hardware Requirements

A GPU that supports hardware encoding
A local network (5GHz recommended)

Software List

Sunshine
Moonlight
Parsec-VDD

Once your hardware is ready, the rest is mostly configuration and a bit of verification.

How to Install and Configure Sunshine

I use Windows for this setup, so these are Windows-first steps.

Install Sunshine from the official release.
Launch Sunshine. The first-time WebUI is usually at https://localhost:47990.
Create your admin account on first login.
Open Settings / Configuration:
- In General, confirm the service is running and enable start-with-system if you want auto-start.
- In Video / Encoder, choose your encoder backend.
- Keep default ports until the full chain is stable.
Open Applications, click Add / New / +, add Desktop, then save.

Useful links:

Build choice on Windows:

Installer: best default choice. Easier service setup and easier updates.
Portable: useful for no-install environments, but you manage more manually.

Service mode in plain terms: Sunshine keeps running in the background as a service, so Moonlight can connect without you re-opening the UI every time.

WebUI and ports:

Default WebUI is 47990 (HTTPS).
If you change ports later, update firewall rules accordingly.

Encoder choice:

NVENC (NVIDIA hardware video encoder)
AMF (AMD media framework encoder path)
QSV (Intel Quick Sync Video encoder path)

After selecting encoder settings, click Save / Apply. Do not leave the page without saving.

NVENC preset:

Start with low-latency presets.
Move toward higher quality only after stability is good.

Bitrate baseline I use:

1080p60: 20-35 Mbps
1440p60: 35-55 Mbps
1600p90: 45-75 Mbps
4K60: 60-100+ Mbps

Practical codec pick:

HEVC / H.265 for better compression efficiency at the same quality.
H.264 when compatibility or decode stability matters more.

Audio setup (important):

In Sunshine Audio, set output device explicitly (avoid auto if you want predictable routing).
If you want sound only on the PC, disable audio redirection.
On Moonlight, go to Settings -> Audio Playback and disable playback there.
In Windows, verify your default playback device is still the local speaker/headphone you want.
Save/Apply Sunshine audio settings after each change.

This avoids the common issue where both PC and tablet play sound at the same time.

How to Install and Configure Moonlight

Moonlight setup is lightweight. Pairing and network correctness are the main points.

Install Moonlight on the tablet.
Make sure tablet and PC are on the same LAN.
Open Moonlight and let it auto-discover the host.
If auto-discovery fails, add host manually with your PC IPv4 address.
Enter the pairing PIN in Sunshine WebUI.

Manual IP steps on Windows:

Press Win + R.
Type cmd, press Enter.
Run ipconfig.
Find the active adapter and read IPv4 Address.
Use that IPv4 address in Moonlight Add Host.

Moonlight links:

First-pass stream settings:

Start at 1080p, 60fps, moderate bitrate.
Scale up after it is stable.

Parameter behavior that matters:

Keep source/output/client resolution aligned when possible.
Keep refresh rates aligned (or integer-related) to avoid uneven cadence.
Watch frame pacing (frame time consistency), not just average FPS.
If bandwidth is tight, reduce resolution/FPS before crushing bitrate.
V-Sync on for smooth office-style use, off for lower interactive latency if needed.
HDR is optional; keep SDR first until the chain is stable.

How to Install and Configure Parsec-VDD

Parsec-VDD is the piece that makes Windows think a second display exists.

Install Parsec-VDD.
Reboot the PC (important: driver enumeration is cleaner after reboot).
Open Windows Display Settings and confirm a new display appears.
Switch display mode to Extend these displays.
Set resolution and refresh rate on the virtual display.

Useful link:

Parsec-VDD Repository

How the virtual display appears:

After driver install + reboot, Windows display stack enumerates it as an available display output.
If your VDD build has an enable toggle/tool, enable the virtual screen there first, then return to Windows Display Settings.

Now the important part: mapping Windows display to Sunshine display ID.

Windows numbers (1/2/3) are logical labels. Sunshine often lists outputs by its own enumeration order (for example Display 0/1/2 or \\.\\DISPLAY1/2). They are often related, but not guaranteed to match one-to-one.

Reliable mapping workflow:

In Windows, make the virtual display easy to recognize:
- set a unique resolution (for example 1280x720), or
- switch it to portrait, or
- drag it to the far left in display arrangement.
In Sunshine WebUI, go to Settings/Configuration -> Video/Display/Capture (wording may vary by version).
Find the target selector (Display / Monitor / Output) and pick one display ID.
Click Save / Apply.
Connect from Moonlight and verify what you see.
If it is the wrong screen, switch to the next display ID in Sunshine, save again, reconnect, and verify again.

This takes a minute once, then stays stable.

Known recovery trick when extend mode does not react:

In Windows Display Settings, switch to Show only on 2.
Click Apply.
Switch back to Extend these displays.

This often refreshes display state and brings the virtual output back into a usable state.

If still broken, check:

You rebooted after VDD install.
Virtual display is not disabled.
Advanced display settings show valid refresh modes.
Manually disable/re-enable the virtual screen once.

Performance Tuning Notes

The goal is stable low latency, not maximum numbers on paper.

Tuning order I use:

Network first
- PC on Ethernet if possible.
- Tablet on 5GHz/6GHz Wi-Fi.
- Avoid heavy transfers on the same LAN while streaming.
Stream parameters second
- Lock stable 60fps first, then push 90/120.
- Raise bitrate gradually.
Encoding path third
- Prefer hardware encoding.
- Avoid software encoding (CPU path) for this use case.
System power and load
- Keep laptop plugged in.
- Use high-performance power mode.
- Close heavy background workloads.

Bandwidth reality:

Codec bitrate is baseline demand, not total overhead-inclusive traffic.
Keep practical throughput headroom (around 25%-40%).

Latency usually accumulates from:

Encode queue
Wireless contention
Router queueing/forwarding
Decode + display sync

Wi-Fi 5 vs Wi-Fi 6 in this use case:

Wi-Fi 5 can be enough.
Wi-Fi 6 tends to reduce jitter under multi-device load.

Monitor GPU correctly:

Watch Video Encode engine utilization, not only 3D usage.
If encode is saturated, lower resolution/FPS/bitrate before anything else.

Technical Notes (Optional Read)

Why This Feels Lower-Latency

The path is designed for real-time frame delivery.

High-level flow:

App renders frame.
Compositor outputs to target display surface.
Sunshine captures that frame buffer.
Hardware encoder (NVENC/AMF/QSV) compresses the frame.
Stream crosses LAN.
Moonlight decodes and presents.

Latency behavior comes from each queue in that path.

Lower-latency encoder presets reduce internal buffering and lookahead.
Network jitter is handled by a jitter buffer on the client side.
Bigger jitter buffer improves stability but adds delay.
Smaller jitter buffer cuts delay but can increase visible hiccups.

Why traditional remote desktop paths often feel slower in this context:

They are generally optimized for desktop readability, reliability, and compatibility.
Their buffering/retransmission behavior is usually more conservative.
That helps office remoting quality, but it is not tuned for minimum interactive frame latency.

Wrap-up

For me, this setup is not a gimmick. It is a practical second screen that I can carry around.

The upside is clear: wireless workflow, low-latency feel, and enough control to tune for your own network and hardware.

It works especially well if you move between places and do not want to buy duplicate monitor setups.

The main thing to remember is that stability comes from process: get the virtual display right, map display ID correctly, then tune bitrate/FPS step by step.

Once configured properly, daily use is mostly just connect and go.

我用 Sunshine 把平板改造成电脑副屏：一套稳定可用的方案

Mon, 16 Feb 2026 00:00:00 GMT

前言

我一直用着一个笔记本电脑，负责我的工作和娱乐需求。但由于我经常有多地周转的原因，我到现在也没给我的笔记本电脑配一个显示器，说实话是我有点太挑了，而且我一想要买两个家里和宿舍都要有一个就干脆不买先了，这样一纠结就以至于我大学快毕业了还没买。

说实在的实在忍受不了我的电脑屏幕不够大，打游戏又不够爽，写代码这块屏幕上能放的窗口又有限。反正我是有点后悔我当初没下定决心整个显示器的，贵点就贵点吧，我就算再挑剔也能爽爽几年。

后来直到我玩上了Apple vision Pro的时候，我才知道有sunshine这种东西，可以将电脑上的游戏画面串流上去。但是我还是不想折腾，他的好处我倒是记住了，于是我最近折腾了一下，为我的电脑用，至于avp？吃灰吧他。

我的平板是华为matepad 11，分辨率是2560*1600，和我的电脑屏幕一样。我试过以该画质 90hz串流，注意到延迟为6ms，体感上也不卡，所以我觉得这套方案是还不错的。

尽管我本人也不是最近天天用这套方案，但是如果你想要拓展出一块副屏，倒是可以考虑一下。

我想要什么样的副屏体验

首先我是要一块拓展的副屏，而不是一块远程控制的屏幕，我不希望平板被误触什么的导致我的鼠标动了，我希望平板放在我的左边，很自然成为我屏幕的衍生。我可以在这边拖放一些串口什么的。这样我可以在主屏幕工作的时候不急着调出来。

其实最好的是那种，主屏幕负责操作，副屏给我放着教程。因为是副屏，所以我可以鼠标拖过去很方便的就可以复制了。我不希望有线，因为我希望我的平板自由点，有时候我需要带着他去别的地方玩金铲铲之战，例如床上。多一根线我感觉也蛮丑的。

整体方案概览

用一张逻辑说明

电脑 → Sunshine（编码） → 局域网 → Moonlight → 平板
               ↓
        Parsec-VDD（虚拟显示器）

一句话说明三者分工：

Parsec-VDD：创造“第二块屏”
Sunshine：把这块屏编码推送
Moonlight：在平板上显示

准备工作

设备要求

支持硬件编码（用显卡或核显专用编码单元做视频压缩）的 GPU
局域网（建议 5GHz，频段更高、同环境下通常干扰更少）

软件列表

Sunshine
Moonlight
Parsec-VDD

那么，在确定你的设备符合标准，接下来我们来讲解一下，如何安装配置这些软件

如何安装配置Sunshine

我这边按 Windows 来写，先给一套能快速跑通的步骤。

下载并安装 Sunshine（建议用官方发布版）。
安装后启动 Sunshine，第一次会提示本地管理页，通常是：https://localhost:47990
首次进入先创建管理员账号和密码。
进入设置后先做三件事：
- 确认服务已运行（可按需开机自启）。
- 选择对应显卡的硬件编码器（NVIDIA/AMD/Intel）。
- 端口先保持默认，先跑通再调，避免排错复杂化。
在 Applications 里添加一个 Desktop 项，方便后续直接串流桌面。

把这几步点实一点，第一次配置会省很多时间：

建完 WebUI 账号后，进 Settings / Configuration，在 General 里确认服务状态是 Running，并把 Start with system（或同类开机启动选项）打开。
进 Video / Encoder，按显卡选 NVENC / AMF / QSV，选完点击页面底部 Save 或 Apply。
进 Applications，点击 Add / New / +，添加 Desktop（不同版本可能叫 Desktop/Command），保存后确认它出现在应用列表里。
音频改完后同样要点 Save / Apply，不保存切页会丢配置。
Moonlight 端关闭声音的位置通常在 Settings -> Audio Playback，关掉后再重连一次让配置生效。

建议先做一次基础验证：

Sunshine 状态是运行中。
Windows 防火墙已允许 Sunshine。
局域网内设备可以发现这台主机。

这一步的目标不是“拉满参数”，而是先把连接稳定建立起来。

下面是我自己长期用下来的进阶安装和参数习惯。

Windows 版本怎么选：

Installer：推荐大多数人用，自动注册服务、自动写必要依赖，后续升级也省心。
Portable：适合你想放在移动硬盘或无安装权限环境，但服务和路径都要自己管。

首次启动的“服务模式”怎么理解：

Sunshine 作为后台服务运行后，即使你没打开主界面，它也能响应 Moonlight 连接。
这对副屏场景很关键，因为你不想每次手动开一堆窗口。

WebUI 端口解释（默认）：

47990：管理页面（HTTPS）。
你改端口可以，但建议先默认跑通，再改；改完记得同步放行防火墙。

防火墙和端口我自己的做法：

首先放行 Sunshine 程序本身（入站/专用网络）。
如果你是手动端口策略，保证 Sunshine 使用端口不被拦截。
跑不通时先回到“同网段 + 默认端口 + 程序放行”这个最小可行组合。

音频这块如果不提前配好，很容易出现“电脑和平板同时出声”或者“声音跑到平板去了”的情况。我自己的做法是先固定音频策略：

在 Sunshine 设置里找到 Audio。
输出设备优先手动指定为你电脑正在用的默认扬声器/耳机，不要放自动。
如果你只想声音留在电脑本机，优先关闭音频重定向（不同版本文案可能是 Do not redirect audio 或类似选项）。
在 Moonlight 客户端里把 Audio Playback 关闭，避免平板端也播放声音。
Windows 里再确认一次“默认播放设备”就是你主机本地设备，避免应用切设备后串流端跟着跑偏。
虚拟音频设备不是必须项，除非你有录制、混音或多路音频路由需求；普通副屏场景不用额外上虚拟声卡。

我一般按这个顺序排错：

先关 Moonlight 音频播放。
再看 Sunshine 是否指定到正确输出设备。
最后在 Windows 声音设置里确认默认设备没有被改。

编码器指定建议（按显卡）：

NVIDIA：优先 NVENC（NVIDIA 显卡自带的视频硬件编码单元）
AMD：优先 AMF（AMD 显卡的视频编码接口）
Intel：优先 QSV（Intel 核显/独显的视频硬件编码路径）

NVENC preset 我建议：

先选低延迟档（Low Latency / P1-P3 这类偏低延迟预设）。
画质不够再一点点往高质量预设调，不要一上来就高画质高缓存。

码率估算我一般用这个粗算方法：

1080p60：20-35 Mbps
1440p60：35-55 Mbps
1600p90（你这种平板常见）：45-75 Mbps
4K60：60-100+ Mbps

一个简单经验公式（仅做起点）： 参考码率(Mbps) ≈ 分辨率像素数 × 帧率 ÷ 5,000,000
然后根据画面复杂度上下浮动 20%-40%。

HEVC vs H.264 怎么选：

优先 HEVC（H.265，压缩效率更高的编码标准）：同画质下码率更低，Wi-Fi 压力小。
兼容或延迟异常时切 H.264（更普及、设备兼容性更高的编码标准）：解码压力更低，老设备更稳。
原则是“先稳定，再压榨画质”。

如何安装配置Moonlight

Moonlight 端配置很轻量，重点是配对和参数起步。

在平板安装 Moonlight（Android/iPadOS 都有版本）。
确保平板和电脑在同一局域网（建议 5GHz）。
打开 Moonlight，等待自动扫描主机；若未扫描到，手动输入电脑 IP。
点击主机后会显示配对码。
回到 Sunshine 管理页输入配对码，完成绑定。

手动输入主机 IP 我自己就按这一套：

在 Windows 按 Win + R，输入 cmd 回车。
在命令行输入 ipconfig。
找你当前正在用的网卡（Wi-Fi 或以太网），记录 IPv4 地址（例如 192.168.1.23）。
在 Moonlight 里点 Add Host（或手动添加主机），填这个 IPv4 地址。
确保平板和电脑在同一局域网，否则能填上也连不上。

第一次串流建议参数：

分辨率先用 1920x1080。
帧率先 60fps。
码率先中档（例如 20-30 Mbps）。
链路稳定后，再逐步提高分辨率和刷新率。

常见问题处理顺序：

黑屏或闪退：先降分辨率和帧率，再检查 Sunshine 编码器。
卡顿：先降码率看是否立刻改善。
连不上：先确认同网段，再看防火墙放行。

Moonlight 这边我平时会额外盯一组参数，能连上和用得稳是两回事。

分辨率匹配策略：

最稳做法是：虚拟屏分辨率 = Sunshine 输出分辨率 = Moonlight 接收分辨率。
三端不一致会触发额外缩放，直接增加延迟和模糊感。

刷新率同步问题：

主机输出 90Hz，但客户端锁 60Hz，会出现节奏不均匀（体感像轻微顿挫）。
最好让源端和收端刷新率成整数关系或一致（60/60、90/90、120/120）。

Frame pacing（帧节奏，指每一帧输出时间间隔是否均匀）建议：

优先稳定帧间隔，而不是追求瞬时高帧。
如果你看到“平均帧率高但体感抖”，通常是 pacing 问题，不只是码率问题。

Bitrate 控制逻辑：

先给足最低稳定码率，避免编码器频繁大幅压缩。
网络余量不够时，先降分辨率或帧率，再降码率，画面会更可控。

V-Sync 建议：

副屏办公/浏览为主：可开，画面更平顺。
极限低延迟交互：可关，减少等待垂直同步带来的附加延迟。

HDR 建议：

默认不建议一上来开启。
HDR 会引入额外色彩链路与带宽压力，先 SDR 跑稳，再评估是否值得开。

如何安装配置Parsec-VDD

Parsec-VDD 的作用是给系统“虚拟出一块显示器”，这是副屏模式的关键。

下载并安装 Parsec-VDD 驱动。
安装完成后重启电脑（不重启经常不生效）。
打开 Windows 显示设置，确认出现新的显示器编号。
显示模式选择“扩展这些显示器”，不要镜像。
给虚拟屏设置分辨率和刷新率（先 1080p/60，再逐步拉高）。
打开 Sunshine WebUI，进入 Display / Video / Capture 相关设置，选择要推送的目标显示器。
在 Moonlight 发起连接，确认平板端画面是否来自你刚才设置的那块虚拟屏。

Sunshine 里“显示器 ID”建议按这个路径操作：

打开 Sunshine WebUI。
进入 Settings/Configuration -> Video/Display/Capture（具体名称按版本文案，找 Display/Monitor/Output 相关项）。
在目标显示器下拉框里选择一个显示输出（常见是 Display 0/1/2 或 \\.\DISPLAY1/\\.\DISPLAY2）。
选完点击 Save / Apply。
回 Moonlight 连接验证画面；如果不是虚拟屏，就回 Sunshine 切换到下一个 ID，再保存再验证。

建议的稳定顺序：

先确认虚拟屏能正常显示桌面。
再让 Sunshine 推送这块虚拟屏。
最后在 Moonlight 对齐分辨率和帧率参数。

实用细节：把虚拟屏在系统中的位置放到主屏左侧或右侧，和你平板真实摆放一致，鼠标跨屏会更自然。

关于“显示器 ID”这件事，我自己踩过的结论是：Windows 里的 1/2/3 和 Sunshine 列表里的索引不一定一一对应。Windows 这个编号更偏逻辑位置，Sunshine 通常按当前枚举到的显示输出顺序列出。

所以我一般不硬猜编号，直接做一个 30 秒确认流程：

先在 Windows 里把虚拟屏拖到一个很明显的位置（比如主屏最左侧）。
在 Sunshine 里先选一个显示器 ID 推送。
平板端看画面是不是那块虚拟屏（窗口、壁纸、鼠标跨屏方向都能很快判断）。
如果推错屏，回 Sunshine 切换到下一个显示器 ID，再验证一次。

我还会再加一个识别标记：在 Windows 先把虚拟屏临时改成一个很容易辨认的参数（例如 1280x720 或竖屏方向），这样 Moonlight 一连上就能立刻看出来是不是选对了那块屏。

为了更快定位，我会临时切到“仅在 2 上显示”，应用后再切回“扩展这些显示器”；很多时候这一来一回能把显示状态直接刷出来。确认完 ID 后再按正常扩展模式使用，后面就不用反复猜。

这块原理了解一下，后面排错会快很多。

Parsec-VDD 官方仓库

虚拟显示器驱动工作原理（简化版）：

驱动向 Windows 显示子系统注册一个“可用显示输出”。
系统拿到这个显示设备后，就能给它分配桌面空间和渲染目标。
Sunshine 再去抓取这个渲染目标并编码推流。

为什么安装后通常必须重启：

显示类驱动加载和设备枚举通常在系统启动阶段完成。
不重启时，驱动文件在，但设备树里可能还没完成重建。

Windows 为什么会把它当“像物理屏”：

关键是驱动提供了显示设备描述信息（含模式能力）。
系统关心的是“有没有合法显示输出接口”，不关心它是不是一根真线插着。

EDID 模拟的意义：

EDID（显示设备能力描述数据）相当于显示器“自我介绍”：支持哪些分辨率、刷新率、色彩能力。
虚拟驱动通过模拟 EDID，让系统相信这块屏支持你配置的模式。

90Hz/120Hz 设置方法（常用路径）：

先在 Windows 显示设置里选中虚拟屏，进入高级显示设置。
在刷新率列表里选择 90Hz/120Hz（前提是驱动声明支持该模式）。
如果列表没有高刷，先确认驱动版本、重启状态、以及该分辨率下是否声明高刷。

我自己踩过一个很典型的坑：驱动装好了，但扩展显示就是没反应。这个时候别急着重装，先按下面顺序试：

在 Windows 显示设置里先切到“仅在 2 上显示”。
点击应用后，再切回“扩展这些显示器”。
如果还是没反应，再逐项确认：
- 机器是否已经重启过；
- 虚拟屏是否被系统禁用；
- 高级显示设置里是否能识别到刷新率条目。
还有一种情况是虚拟屏状态卡住，这时手动断开再重新启用虚拟屏通常能恢复。

性能优化建议

这套方案的核心是“稳定低延迟”，不是盲目拉满画质。

建议按下面优先级调：

网络优先：
- 电脑尽量有线连路由器。
- 平板走 5GHz/6GHz Wi-Fi，尽量避免 2.4GHz（低频段覆盖广但拥挤时更容易干扰）。
- 串流时减少同网段大流量下载。
参数优先：
- 先稳定 60fps，再尝试 90/120fps。
- 先中码率，再逐步上调。
编码优先：
- 优先硬件编码（NVENC/AMF/QuickSync）。
- 避免软件编码（由 CPU 通用计算完成编码），CPU 抖动会更明显。
系统优先：
- 笔记本插电并切高性能模式。
- 关闭高占用后台任务。

一个实用排错流程：

先把分辨率、帧率、码率各降一档。
看是否立即稳定。
若有效，再逐项回调，找到设备上限。

这个流程比一次性拉满再盲调更省时间。

下面这套工程化观察指标是我日常排错时最常用的。

带宽与码率关系（实操版）：

编码码率是“最低网络需求”，不是“总网络占用上限”。
真实链路要留 25%-40% 余量给协议开销和波动。
例如你计划 50 Mbps 码率，实际最好有至少 70 Mbps 的稳定可用吞吐。

局域网延迟主要来自四段：

编码等待（GPU 编码队列）
无线介质争用（Wi-Fi 空口竞争）
路由转发/排队
解码与显示同步

Wi-Fi 5 vs Wi-Fi 6（两代无线协议标准）体感差异（副屏场景）：

Wi-Fi 5 在单设备下也够用，但高并发时抖动更明显。
Wi-Fi 6 的调度机制更好，多个设备同时在线时延迟波动通常更小。
你如果追求稳定高刷，Wi-Fi 6 往往更容易“稳住下限”。

笔记本插电的重要性：

不插电时很多机型会限制 CPU/GPU 功耗墙。
编码器频率一旦被压，延迟和帧时间稳定性都会掉。
所以调性能前先插电，这个收益通常比你调半天参数还大。

GPU 占用监控建议：

重点看 Video Encode 引擎占用（GPU 里专门负责视频编码的硬件模块），不只是 3D 占用。
如果编码占用长期顶满，先降分辨率/帧率/码率。
同时看显存和温度，热降频会直接体现在“偶发卡顿”上。

技术原理（可选阅读）

为什么这种方式延迟更低？

核心原因是：这条链路本身就是为“实时画面传输”设计的。

实际体验里，主要是下面这几段在决定延迟上限：

Sunshine 走低延迟串流路径，编码缓冲更小。
编码与解码都可走硬件加速，单帧处理时间更短。
Moonlight 客户端对实时显示做了优化，输入到显示路径更短。
全程局域网传输，网络路径短、抖动小、无需公网中转。

所以体感上会更“跟手”，更接近真实副屏，而不是传统远程控制窗口。

把整条延迟链路按工程视角拉开看，会更容易理解为什么参数要那样配。

帧缓冲抓取流程（简化）：

应用把画面提交给系统合成器。
Sunshine 从目标显示输出抓取当前帧缓冲（当前时刻准备送到屏幕的图像数据）。
抓到的帧进入编码队列，等待硬件编码。

GPU 硬件编码 pipeline：

帧数据进入 NVENC/AMF/QSV 编码单元。
编码单元按预设做帧内/帧间压缩。
输出码流后交给网络发送线程。

NVENC 的低延迟路径怎么理解：

低延迟 preset 会减少缓存深度和前瞻处理。
代价是同码率下画质可能略差，但交互延迟更短、更稳定。
副屏交互场景通常更吃“响应速度”，所以这笔交换很值。

网络传输中的 jitter buffer（用于吸收网络抖动的小缓冲区）：

客户端会保留一小段缓冲来对抗网络抖动。
缓冲太大，稳定但延迟高；缓冲太小，延迟低但容易抖。
实际调参就是在“稳定性”和“绝对低延迟”之间找平衡点。

为什么传统远程桌面协议延迟通常更高（只讲原理）：

它更偏“桌面可读性与兼容性”目标，不是为高帧实时画面设计。
编码策略常更强调压缩效率和可靠传输，缓冲和重传策略更保守。
输入、编码、传输、合成链路里的安全冗余更多，换来的是更稳定的远程办公体验，但不是最低交互延迟。

小结

这套方案我用下来，把平板真的变成了一块可长期使用的副屏。写代码、查文档、看监控面板这种场景，体验已经非常接近实体第二屏。

它的优点很明确：无线、低延迟、参数可控，而且成本比再买一套固定显示器低不少。尤其是你本来就有平板，改造成本几乎只剩时间。

适用场景我觉得也很清楚：宿舍党、经常搬地方办公的人、临时搭建双屏环境的人，都会明显受益。固定工位党当然也能用，但固定显示器依然是最省心的终点方案。

要注意的地方也就几件：网络质量、编码设置、虚拟屏参数一致性。前面这些步骤看起来多，其实第一次配好后，后面基本就是“打开就用”。

如果你是第一次折腾这类串流副屏，我建议先按保守参数跑稳，再一点点加画质和刷新率。别一上来拉满，先稳定，体感会好很多。

其实也不止可以用来做副屏，sunshine你也可以后面配置好，平板串流你电脑上的游戏，然后你在床上，平板放腿上，接个手柄玩什么的。

我是如何稳定追番的

Sat, 14 Feb 2026 00:00:00 GMT

引言

如何追番，或者说如何稳定地追番？

当你想追一部新番时，有可能这个番需要某个 app 会员，也可能国内还没引进。就算引进了，也得等几周审核延迟。经典如 Lycoris 这部原创动画，在“无法预测的命运之舞台”里，我们每周都在等下一集到底讲什么。

我也试过直接看日本电视台放映，靠我那点蹩脚日语硬啃，结果看得一脸懵。真的很急。所以当时 B 站虽然也能看，但进度比官方晚了好几周。后面剧情大家都知道，我那会儿追到后面，感觉自己简直是小丑。

你有没有想过，你随便搜个番名，找到一个网站就看了，但资源其实并不稳定，有时候画质糊得离谱；有些番你也不想看和谐版；而且我自己还希望看番能有弹幕。其实这些需求是可以被满足的，这篇文章就聊聊，我是怎么把“追番”这件事，慢慢做成一个稳定流程的。

warning

本文仅用于分享个人观影流程与工具使用经验。请根据你所在地区的法律法规与平台条款，合法观看与使用相关软件。

1. 如何获取资源

先把话说清楚：我这篇不是教你“去哪里找盗版”，而是教你怎么少踩坑、稳定看番。我的做法是先看本地区可用的合法平台，再决定要不要做本地播放和订阅（疯狂叠甲）。

为什么我要下载到本地播放？

不是每个人都必须本地播放，但如果你对画质、字幕、进度和弹幕有要求，本地播放通常更稳。平台端胜在方便，本地端胜在可控，我自己是两套并行。

你可以理解成：

平台端：适合快速开看、补番、跨设备。
本地端：适合高画质、字幕控制、收藏归档。

如果你只是轻度追更，平台端就够。如果你跟我一样会在意字幕和解码，那本地端会更舒服。例如，对我来说，我国漫和日漫都看，像凸变英雄X这种番我是每周更新那天12点蹲着看，一刻都不想等。而超时空辉夜姬这种番，我更注重我极限的观影环境，我必须搞到最清晰的片源之类爽爽看。

什么是磁力链？

磁力链（Magnet URI）是一个技术标识，本质上是“告诉下载器这是什么内容”，不是“告诉你去哪个网站拿内容”。

它常见于 P2P 场景。P2P（Peer-to-Peer）可以简单理解成“大家互相传数据”，不是完全依赖单一服务器，所以速度会受在线节点、网络质量、做种数量影响。

这里还是那句话：技术是中性的，使用必须合法。在某些国家，例如德国，通过 BitTorrent 等 P2P 技术下载受版权保护的内容可能会面临法律风险，因为此类协议通常同时涉及文件上传（分发）。现实中确实存在因版权侵权而收到律师函与罚款的案例，因此在使用此类技术前，应充分了解当地法律环境。(你也不想看个番被罚款一堆欧元吧)

那我要如何获取番剧资源的磁力链呢？

我不在这里提供任何未授权来源路径。你要做的是先确认作品在你地区的授权状态，再从合法渠道观看或获取你有权使用的内容。

如果你只是想先开始看，建议先用下面这些正规平台试着追：

但是这毕竟不是你想看到的内容，所以我为你推荐一个获取番剧磁力链的网站Mikan，接下来的教程我们会议电锯人蕾塞篇的下载为例。你进入网站后直接搜就行了，能搜到后挑选一个你可以接受的画质和字幕类型的资源复制磁链。

什么是字幕组？简繁内封又是什么？

这些词你迟早会遇到，提前知道能省很多时间。

字幕组你可以理解成“做翻译、时间轴、校对、压制”的团队。简繁内封一般是指字幕在文件里已经封装好，同时带简体和繁体轨道。

如果你遇到“字幕有但显示效果很差”，先查三件事：播放器字幕引擎、字体是否缺失、字幕轨是否选对。字幕组很多时候是为爱发电，他们也不容易，每当有新番更新，你不能第一时间在这些番剧资源网站获取到熟肉是正常的，毕竟人家也需要时间做对吧。基本等个第二天就应该能看到了。

磁力链资源要怎么下？

我的建议是：先装一个稳定下载器，路径一次配好，不要每次临时改。这样后面播放器、弹幕、RSS 才能串起来。

qbittorrent

我目前主力就是 qBittorrent，最大的原因是它很“纯工具”：干净、没那么花里胡哨，而且你拿到磁力链接后操作非常直接。

官方下载：

如果你官网打不开，可以直接用 GitHub 下载，Windows 按这个选就行：

打开 qBittorrent GitHub Releases 页面，选最新稳定版本（不要选 pre-release）。
点开该版本的 Assets 列表。
Windows 用户优先下载安装包：文件名通常是 qbittorrent_版本号_x64_setup.exe（64 位系统）。
如果你只想便携版，不想安装，选 x64.zip 这类压缩包，解压后运行 qbittorrent.exe。
不要下载 Source code (zip) 或 Source code (tar.gz)，那是源码，不是给普通用户直接安装的。

如果你是第一次用，我建议你就按下面这套来，基本不会迷路。

第一步，先装好 qBittorrent，打开后进 工具 -> 选项 -> 下载，把默认保存路径设置好，比如 AnimeWorkspace/_incoming。
第二步，拿到磁力链接后，直接复制。qBittorrent 一般会自动弹出“添加种子”窗口；如果没弹出，就手动点左上角“添加链接”（链条图标）把磁力贴进去。
第三步，在“添加种子”窗口里重点看三件事：保存路径、文件列表、是否“立即开始”。确认没问题再点“确定”。
第四步，回到主界面看状态。状态从“正在下载”变成“正在做种”就说明文件已经下完了。

你真正关心的“下完之后怎么看对不对”，我建议就查这几项：文件大小是否异常、视频时长是否正常、字幕轨是否存在。没问题再挪到你正式看片目录。

它的优点我用人话总结就是三条：
第一，稳定，长时间挂着也不太容易抽风。
第二，可控，你要存哪、怎么分类都能自己定。
第三，对 RSS 和自动化规则支持好，后续追更省心。

缺点也有：
第一，界面偏朴素，新手第一次看会觉得信息很多。
第二，速度不一定一直快，受做种人数和网络环境影响很大。
第三，你如果完全不想折腾任何设置，会觉得它“没那么傻瓜”。

你提到“下载时看到各个国家的国旗是什么意思”，这个很多人第一次都会问。
在 qBittorrent 里，国旗一般表示当前连接到的 Peer（节点）IP 归属地。简单理解就是：你正在和哪些国家/地区的节点交换数据。
它不是内容来源的法律背书，也不是质量保证，只是一个网络地理信息参考。
另外这类标记基于 IP 数据库，会有误差，所以你看到国旗和你想象不一样也很正常。

夸克网盘（非广告）

我会把夸克当成磁力下载的一种“加速方案”，核心原因就是速度体感确实快。
按我自己的网络环境（家里千兆宽带）来看，夸克网盘在会员状态下，很多任务能跑到 50-60 MB/s，这在日常使用里已经很舒服了。

和 qBittorrent 对比的话，差别不一定是“软件谁更强”，而是下载模式不同。
夸克更像“先让平台服务器把资源拉好，再给你下”，所以速度表现常常更稳定。
qBittorrent 是典型 P2P 直连模式，速度会更依赖当时在线节点数量、对端上传能力和你的网络连通性。节点好时它也能很快，节点差时就会掉速。

所以更准确的说法是：夸克在会员前提下，速度上限和稳定性通常更容易跑出来；qBittorrent 的速度波动更大，但透明度和可控性更高。

下载入口：

夸克官网

它的优点是跨设备方便，磁力资源下载快。而且你只要复制磁力链接了他就能给你弹出一个下载窗口。

迅雷（非广告）

迅雷在圈子里经常被叫“吸血雷”，这个说法不是空穴来风，主要是历史上大家对它在 P2P 生态中的行为有争议。
“吸血”这个词的意思大概是：下载时拿得多、分享得少，或者借助加速体系让普通节点承担更多上传压力。

从用户体感看，你会觉得它“我这边下得很快”；但从网络生态角度看，如果大量客户端都偏向只拿不共享，整个网络健康度会下降，最后大家都变慢。
这也是为什么老 P2P 用户对“吸血雷”这个称呼非常敏感，它本质是在讨论公平共享的问题。

下载入口：

迅雷官网

2. 选择你的播放器

下载只是第一步，真正决定你“看得爽不爽”的是播放器。尤其是解码能力和字幕支持，这两个差一点，体验会差很多。

potplayer

PotPlayer 我自己一直当主力本地播放器用，它的核心优势就是解码强、字幕细节能调、兼容性高。你手里文件格式比较杂的时候，它通常都能稳稳播出来。

官方下载：

PotPlayer 官网

安装我建议这样走，基本不踩坑：

打开官网后，下载 Windows 版本安装包。
双击安装，一般保持默认下一步就行。
第一次打开播放器后，先别急着调一堆参数，先拖一个你常看的视频进去试播。
确认能正常播放后，再进设置做基础优化。

基础设置我建议先配这几项，够用了：

关联常见视频格式（mkv、mp4），以后双击文件直接用 PotPlayer 打开。
在“字幕”里开启自动加载同名字幕文件，减少手动操作。
在“视频”里确认硬件解码是开启状态（一般默认就开）。
音频输出先保持默认，不要第一天就上复杂滤镜。

它的好处我按真实体验讲：

解码能力强：很多平台播放器播不顺的封装，PotPlayer 能播。
字幕控制细：字体、描边、阴影、位置都能调，字幕党很舒服。
音轨切换方便：双音轨、外挂字幕、内封字幕切换都快。
本地稳定：你不用被平台 UI 和功能变化影响。

新手最常见的问题其实就三个：

卡顿：先看硬解有没有开，再看是否误开了高负载滤镜。
字幕怪异：先换字幕渲染方式，再检查系统字体是否缺失。
没声音或声道怪：切一下音频输出设备，或者切到另一个音轨测试。

我自己的使用流程很简单：双击文件打开 -> 右键确认字幕轨和音轨 -> 如果不对再进设置微调。不要一开始把播放器改得太“极限”，先稳定，再个性化。

dandanplay

dandanplay 我把它理解成“专门给看番做的播放器”。它不是参数最多的，但它把播放、弹幕、番剧信息、文件匹配这些事情放在了一起，对追更党特别省心。

官方下载：

如果你想在 Windows 上从 GitHub 直接下，我建议按这个顺序来：

打开发布页后，先看版本标题，优先选带 windows- 的最新版本。
点开这个版本的 Assets。
你要下载的文件优先选安装包：文件名里通常会有 Setup 和 .exe。
如果你是 64 位 Windows，优先选带 x64 的安装包（如果有）。
如果你不想安装，想要绿色版，就选 .zip 压缩包，解压后运行 dandanplay.exe。
不要下 Source code (zip) 或 Source code (tar.gz)，那是源码，不是给普通用户直接安装用的。

下载和安装也很直白：

打开官网，下载对应系统版本。
双击安装，默认路径安装即可。
首次打开后，先把你的番剧文件夹加入媒体库。
让它先扫描一次，这样后面识别速度会快很多。

它的核心好处我总结成四个点：

看番一体化：本地播放和弹幕不用来回切软件。
识别友好：对番剧命名和集数识别通常比通用播放器更友好。
弹幕体验好：匹配、加载、筛选都做得比较顺手。
上手门槛低：不想折腾大量参数也能直接用。

第一次使用我建议按这个顺序：

先导入一个作品文件夹，确认集数识别正确。
打开一集，先看弹幕是否时间轴对齐。
在设置里把弹幕透明度、速度、字号调成你自己舒服的值。
最后再决定是否开启更多过滤规则（比如屏蔽重复弹幕）。

很多人一开始会遇到“有弹幕但看着很乱”，这不是软件坏了，通常是参数没调好。你先把弹幕速度放慢一点、轨道数量适中、透明度降低一些，观感会立刻好很多。

如果你同时装了 PotPlayer 和 dandanplay，我建议分工用：

想细抠画质和字幕样式，用 PotPlayer。
想轻松追更看弹幕，用 dandanplay。

这样组合起来，基本能覆盖绝大多数追番场景。

夸克网盘

夸克这边我更多是把它当轻量播放器。

优点是你换设备很方便，缺点是解码和字幕微调不够细。我的建议是把它放在“补充位”，不是“主力位”。

3. 如何用 dandan play 配置弹幕

弹幕这块真的是细节决定体验。你参数配对了会很舒服，配错了就会觉得很吵。

什么是弹幕？

弹幕就是绑定时间轴的评论流。它的价值在于让你看到同一剧情节点上别人的实时反应，这种“异步共时”是番剧体验里很有趣的一部分。

什么是弹幕源？

弹幕源可以理解成数据来源。不同来源，密度、质量、审核风格、时间轴精度都不一样，所以同一集在不同源里的观感差异会很大。

选择弹幕源

我的做法很实在：

先拿一集做测试，看关键剧情点是否对齐。
再看内容质量，是否刷屏或重复太多。
最后才看数量够不够。

我建议固定 1-2 个你习惯的源，不要每周来回切。固定后，再把透明度、速度、字号上限这几个参数也固定，观看体验会稳很多。

4. 什么是 RSS 订阅？

先说人话版定义：RSS 就是“自动更新通知”。
你可以把它理解成“订阅箱”，只要对方有新内容，就会按统一格式推送给你，你不用每天手动去翻。

技术上它是一种基于 XML 的内容订阅标准，常见后缀是 feed、rss.xml、atom.xml。
它不会直接帮你下载文件，它做的是“发现更新”。下载动作要靠后面的工具规则来执行。

为什么这东西对追番有用？因为它解决了最烦的事：你不用记“今天周几更新、要去哪个页面看”。
你只要把订阅源配好，更新会自己进来，你再决定“手动下”还是“自动下”。

如何使用 qbittorrent 进行番剧订阅？

在 qBittorrent 里，RSS 的分工很清楚：
RSS 负责发现新条目，下载规则负责判断这个条目是否要下载。

下面这套是我自己在 Windows 上的实操流程，给你一个能直接照做的版本。

第一步，先打开 RSS 功能。
进入 qBittorrent 顶部菜单 视图，勾选 RSS 阅读器，左侧会出现 RSS 面板。
如果你第一次开，它会提示初始化，直接确认就行。

第二步，添加订阅源。
在 RSS 面板里点“新建订阅”或“添加 feed”，把你已有的合法 RSS 链接贴进去。
比如官方公告 feed、你已授权内容的平台更新 feed、或公开可订阅的节目更新源。

第三步，确认源是否正常更新。
添加后先看它会不会拉到新条目。
如果一直空白，先检查三件事：链接是否有效、网络是否可访问、源本身是否近期有更新。

第四步，创建下载规则（核心）。
进入 RSS 下载器（有时叫“自动下载规则”），新建一条规则。
我建议先填这几项：

必须包含：作品名 + 季号，比如 Lycoris + S01。
可选包含：1080p、简体、CHS 这类你偏好的标签。
必须不包含：你不想要的关键词，比如 合集、预告、NCOP（按你需求）。
保存目录：指向你固定的下载目录，比如 AnimeWorkspace/_incoming。
智能过滤：同一集只抓一次，避免重复下载。

第五步，先手动试跑，不要一上来全自动。
先让它跑 3-7 天，观察误匹配情况。
误匹配多，就收紧“必须包含”；漏抓多，就放宽关键词或加同义词。

第六步，再决定是否自动下载。
当你确认规则稳定后，再勾选自动下载。
这时候你就基本进入“更新来了就排队，排队完你再看”的状态了。

我给你一个更稳的规则思路，尤其适合新手：

一部番先只建一条规则。
先把标题匹配做准，再去加清晰度/字幕细分。
规则名称写清楚（比如 2026Q1_Lycoris_S01_1080p），后面维护不乱。
每周固定检查一次命中结果，微调后再放着跑。

最后补一个常见问题排错清单，你文章里读者会很需要：

RSS 没更新：先检查 feed 链接是否失效，再看网络代理或 DNS。
条目出现但不下载：通常是规则关键词没命中，先看标题文本再改规则。
总是下错版本：必须包含太宽，补上季号/分辨率/字幕标签。
重复下载：开启智能过滤，或在规则里限制同标题重复。
下载到了错误目录：规则里单独设置保存路径，不要只用全局默认目录。

你把 RSS 这块配顺之后，追更真的会轻松很多。
不是说从此不用管，而是从“每天手动找更新”，变成“每周花几分钟维护规则”。

小结

根据我的教程，你应该学会了如何追番。实话说自23年起我养成了在本地看番的习惯后就改不掉了，是一个玩nas的老乡教我的。今年我教了一个纽约美高这个办法，他惊叹：我简直是在现场看一样！太清晰了！一定一定要管理好下载番剧的文件夹，因为下载的后一段时间不看你就大概率忘了你下的是啥番了（提供文件夹名称）。恕我不能提供更详细图文并茂的教程，如有问题，自行谷歌或者去b站搜索视频按照步骤操作。

享受看番的过程，或许您后面会走上一条路折腾nas什么的来下载番剧看番，但不要忘了旅途最初的目的。

希望您能通过我的分享更好的看番。

How I Keep My Anime Watching Stable

Sat, 14 Feb 2026 00:00:00 GMT

Introduction

How do you keep up with anime, or more importantly, how do you keep up consistently?

When a new show starts, sometimes it needs a paid membership on one app, sometimes it is not even licensed in your region yet, and sometimes even after licensing, you still wait extra weeks for delayed release windows. A classic case for me was Lycoris Recoil. Every week I was waiting for the newest episode like my life depended on it.

I even tried watching Japanese TV broadcasts directly with my very questionable Japanese skills. That ended exactly how you expect: confusion, panic, and me staring at the screen like a lost NPC.

So yes, I was in a hurry. Platforms like Bilibili could work, but often lagged behind official release timing by weeks. And if you know that show, you know why being late felt rough. I felt like a clown by the time I caught up.

Have you had this too: you search a title, click a random site, and the video quality is blurry, unstable, or heavily edited; subtitles are inconsistent; and if you like watching with danmaku, the experience is all over the place. The good news is these problems can be improved. This post is basically how I made my anime-watching flow less chaotic and more reliable.

warning

This post only shares personal workflow and tool usage ideas. It does not provide unauthorized content sources. Please follow local laws and platform terms in your region.

1. How I Get Content

Let me be clear first: this is not a piracy tutorial. This is a “how to reduce chaos” tutorial.

My order is simple: check legal options in my region first, then decide whether I need local playback for better quality/subtitle control.

Why do I still download for local playback?

Not everyone needs local playback. But if you care about quality consistency, subtitle control, release timing, and archive stability, local playback helps a lot.

I treat it like this:

Platform streaming: fast and convenient, great for casual watching.
Local playback: better control, better consistency, better for rewatching.

If you watch casually, streaming may be enough. If you are picky like me, local playback is often worth it.

What is a magnet link?

A magnet link (Magnet URI) is a technical identifier. It tells a client what content hash to look for; it does not automatically mean “this is where to legally get content.”

You will often see it with P2P workflows. P2P (Peer-to-Peer) means participants exchange data with each other instead of relying only on one central server. So speed can change based on peers online, their upload rates, and your network path.

Technology itself is neutral. Usage still needs to be legal.

So how do I get anime magnet links then?

I do not provide unauthorized source instructions here.

My practical approach: confirm licensing in your region first, then use legal channels. If you just want to start watching today, these are common legitimate platforms to check first:

Catalogs vary a lot by region, which is normal. I usually build a weekly watchlist first, then map each title to whichever legal platform actually has it.

What are fansub groups? What does dual Chinese internal subtitles mean?

You will see these terms sooner or later.

A fansub group usually handles translation, timing, editing, and packaging. “Internal subtitles” means subtitle tracks are embedded in the media container. “Dual Chinese” often means both Simplified and Traditional subtitle tracks are included.

If subtitles exist but look terrible, check three things first: subtitle renderer, missing fonts, and whether you selected the correct subtitle track.

How do I download from a magnet link?

I will only cover tool usage here, not source discovery.

The practical idea is simple: use one stable downloader and keep your path settings consistent. That way your player, danmaku workflow, and RSS setup all stay clean.

qbittorrent

qBittorrent is still my primary client. It feels like a proper tool: clean, transparent, and direct.

Official download links:

If the official site is inaccessible for you, GitHub releases work fine. On Windows, use this quick rule:

Open Releases and pick the latest stable version (not pre-release).
Expand Assets.
For most users, download the installer: usually qbittorrent_<version>_x64_setup.exe.
If you want portable mode, download the x64.zip build and run qbittorrent.exe.
Do not download Source code (zip/tar.gz) unless you actually plan to build from source.

If this is your first time, here is the beginner-friendly flow:

Install qBittorrent.
Go to Tools -> Options -> Downloads, set a default save path (for example AnimeWorkspace/_incoming).
Copy your magnet link.
qBittorrent usually pops up an “Add Torrent” window automatically.
If it does not pop up, click the chain/link icon and paste it manually.
In the dialog, check save path, file list, and whether to start immediately.
Click confirm and watch status.
When status changes from downloading to seeding, download is complete.

What I check before moving a file into my main library:

File size looks reasonable.
Video duration makes sense.
Subtitle track exists and is usable.

Pros in plain language:

Stable for long-running tasks.
Highly controllable paths and categories.
Great RSS automation support for weekly updates.

Cons in plain language:

UI is not “cute beginner mode”; it looks technical.
Speed fluctuates with peer/network conditions.
If you hate all settings screens, it may feel a bit nerdy.

About those country flags in peers list (this confuses many people):

The flag usually represents the IP geolocation of connected peers. In plain words, it shows where those network nodes are estimated to be.

It is not a legal guarantee, not a quality score, and not always perfectly accurate.

Quark Drive (non-sponsored)

I use Quark as an acceleration option in some cases, mostly for convenience.

In my home setup (gigabit line), with membership, I can often see around 50-60 MB/s on many tasks.

Compared with qBittorrent, the difference is often not “which app is objectively stronger” but “how the backend works.” Quark can feel more stable in speed because part of the process is platform-assisted. qBittorrent is direct P2P, so it can be very fast on good swarms and slower on weak ones.

Download link:

Quark official site

Xunlei (non-sponsored)

Xunlei is often called “leech thunder” in old P2P discussions. That label comes from long-running debates about fairness in sharing behavior.

The core argument is simple: if too many clients take bandwidth but contribute less back, swarm health goes down and everyone eventually suffers.

Download link:

Xunlei official site

2. Choose Your Player

Downloading is only step one. Playback quality is where your daily experience is won or lost.

potplayer

PotPlayer is my main local player when I care about details.

Official download:

PotPlayer official site

Beginner install path:

Download Windows installer from the official page.
Run installer and keep default options unless you have specific needs.
Open one known-good video first before touching advanced settings.
After confirming playback works, do basic tuning.

Basic setup I recommend first:

Associate common formats (mkv, mp4).
Enable auto-loading same-name subtitle files.
Ensure hardware decoding stays enabled.
Keep audio output defaults initially.

Why it is good:

Strong decoding compatibility.
Excellent subtitle styling control.
Fast switching between tracks/subtitles.
Stable local experience without platform UI drama.

Common beginner issues:

Stutter: check hardware decode and heavy filters.
Weird subtitle rendering: check renderer mode and fonts.
Audio oddities: switch output device or test another track.

My normal use is boring and reliable: open file, confirm subtitle/audio tracks, only tweak settings if needed.

dandanplay

dandanplay is very anime-friendly. It combines playback, danmaku, and show metadata in one place.

Official download:

If you download from GitHub on Windows:

Pick the latest release with windows- in the tag/title.
Open Assets.
Prefer installer .exe with Setup in filename.
On 64-bit Windows, prefer x64 builds when available.
If you want portable mode, choose .zip and run dandanplay.exe.
Do not download Source code (zip/tar.gz) for normal use.

Initial setup flow:

Install app and launch.
Add your anime folder to library.
Let it scan once.
Open one episode and verify match.
Adjust danmaku opacity/speed/font size to comfort.

Why it is good:

Anime-focused workflow out of the box.
Better title/episode matching than many generic players.
Danmaku integration is smooth.
Lower setup friction for regular users.

If danmaku looks chaotic at first, that is usually settings, not app failure. Lower speed a bit, reduce track count, and increase transparency.

Quark Drive

I use this as a light playback fallback on other devices.

Convenient for quick switching, less ideal for fine subtitle/decoder control.

3. How to Configure Danmaku in dandanplay

Danmaku quality is all about tuning. Good settings feel immersive; bad settings feel noisy.

What is danmaku?

Danmaku is timestamped viewer commentary synchronized to specific timeline moments.

The fun part is you can still “watch with others” asynchronously.

What is a danmaku source?

It is where danmaku data comes from. Different sources vary in volume, quality, moderation style, and timing precision.

Choosing a danmaku source

My practical order:

Check timeline alignment first on one test episode.
Check text quality (spam/repeat/noise).
Only then evaluate quantity.

I recommend keeping 1-2 stable sources instead of switching every week.

4. What is RSS Subscription?

RSS in plain English: automatic update notifications.

Think of it as a subscription inbox. When a source updates, you get a structured feed item without manually checking pages every day.

Technically it is a standardized feed format (often XML-based, such as RSS or Atom). It helps discover updates; it does not automatically download files by itself.

How to use qBittorrent for anime RSS subscriptions?

In qBittorrent:

RSS discovers new items.
Download rules decide what to grab.

Windows-friendly setup flow:

Open qBittorrent View and enable RSS Reader.
Add your legal feed URL in RSS panel.
Confirm feed updates are visible.
Open RSS Downloader (auto-download rules) and create one rule.

I recommend starting with these fields:

Must contain: title + season keyword.
Optional contains: 1080p, language tags, preferred release tags.
Must not contain: trailers/NCOP/other unwanted items.
Save path: your fixed download folder.
Smart episode filter: avoid duplicates.

Start conservative:

Run manually for 3-7 days.
Check mis-matches.
Tighten or relax keywords.
Only then enable full auto-download.

Quick troubleshooting list:

Feed does not update: verify URL/network/source activity.
Items appear but nothing downloads: rule mismatch.
Wrong versions downloaded: tighten must-contain filters.
Duplicate downloads: enable smart filters.
Wrong folder: set per-rule path explicitly.

Once this is tuned, weekly tracking becomes much easier. You move from “daily manual searching” to “quick weekly rule maintenance,” which is honestly a huge quality-of-life upgrade.

如何搭建一个个人博客网站

Thu, 12 Feb 2026 00:00:00 GMT

前言

当我发现我的越来越记不住我的技术和想法时，我有时候会在失眠的深夜里用我手机的备忘录进行记录，但内容量相当有限，而且我无法在其他设备随时访问到我的备忘录里的内容。今年1月我在失眠的夜晚打算要是有空就搭建一个个人博客网站，我要写博客记录下来有意义的内容，为了我自己，我教过的学生，以后或许我也会有更多的学生需要。但是我实在很忙碌，最近又刚在江苏省出差完回来，回家我依旧失眠的一个夜晚，我想起了这一件事，但可惜那会是凌晨，我不好方便去打扰我有做过个人博客的朋友们，而且我预估的完成时间可能是一周。第二天早上我问了问我的高中同学Herbert Skyper，他的答复是一周，但是他是用Vue纯手搓并没有用成熟的博客框架只是想手搓个前端玩玩，我25去哈工深找他玩的时候倒是又和他聊过相关的事情，域名费大概一年几十块(七八十好像)，服务器我忘了他怎么解决了可能部署到学校的一些平台上了。做网站最麻烦之一的问题就是你需要一个域名（有特点需求还需要备案流程），还有一个尽量24小时都开着的稳定性能足够的电脑（一般来说服务器符合），还有公网IP（也是有办法解决，但是不要折腾是最好的）等等麻烦的事情。不过Skyper和我提到了一嘴他的同学有用Astro的，一个成熟的博客框架。后面我的朋友kymi回复了我，他用Hexo写的，他的个人博客里也有对应的教程《如何用Hexo搭建博客》。而且他说也不是很费时间，部署在github上，这样就解决了域名和服务器费用。

需求分析

我需要的是什么？

我需要的是一个备忘录pro，我随时可以查看，并且其他人也能看，而且我希望我不会因此花费太多钱和时间。内容为王，但是我又希望可以做点美观个性的小情趣，为世界留下一些我的存在吧算是。我希望我的博客风格是简洁理性克制的，但是又温柔的，有些许多彩的小东西点缀，让人会心一笑。

技术路线

根据前言，既然如此那我为什么选择了Astro了呢？因为我打算看看有哪些博客框架，他们之间都有什么优缺点，什么最适合我。由于我用Chatgpt多年，他对我的掌握的技术水平有一定了解，我将他的推荐内容整理成以下表格

博客框架对比分析

框架	技术栈	构建速度	写作体验	组件/交互能力	扩展性	GitHub Pages 适配	适合人群	可能的坑
Hexo	Node.js	中等	上手简单，主题多	较弱（偏模板型）	中等	成熟稳定	纯写作、中文生态用户	Node 依赖偶尔折腾
Hugo	Go	极快	结构清晰	一般（偏内容驱动）	中等	非常稳	追求速度、低运维	主题配置偏工程化
Astro	现代前端（支持 React/Vue/Svelte）	快	Markdown / MDX 体验好	强（组件化混排）	强	需注意 base 路径	前端开发者	自由度高，需要自己决策
Next.js / Nuxt	React / Vue 全栈	中等	良好	非常强	极强	静态导出需处理资源前缀	未来想做平台级网站	对纯博客略重
VitePress / Docusaurus	Vite / React	快	文档体验极佳	中等	中等	非常稳	技术文档型内容	博客氛围较弱
Jekyll	Ruby	中等	传统 Markdown	较弱	中等	原生支持	想最少折腾部署	现代化程度一般

决策导向总结

需求类型	推荐方案	理由
纯写作、主题成熟、少改代码	Hexo / Hugo	经典稳定
大量技术文章、追求构建速度	Hugo	构建速度极快
博客 + 项目展示 + 前端交互	Astro	Markdown + 组件混排优势明显
未来可能升级成个人平台	Next.js / Nuxt	全栈能力强
偏技术文档整理	VitePress / Docusaurus	目录与结构管理优秀

Chatgpt和我说，虽然Astro自由度高，需要自己决策可能是一个坑，但对我反而或许是一个优势了，我可以挑选我喜欢的组件，至于域名和服务器问题，我一开始想的是 Cloudflare，但是既然项目要上传github，那么github pages反而相当的方便，因为我设置完后，每次只要push就能更新了，相当的方便。下面我附上部署与成本难度的表格

部署与成本维度

项目	现实情况
服务器费用	GitHub Pages / Cloudflare Pages / Vercel 基本为 0
域名费用	默认可用 username.github.io（免费）；自定义域名通常需要付费
运维成本	静态站点基本为 0 运维

既然Astro支持现代前端Vue，那我要选用什么组件呢， 你的技术路线也其实决定博客风格与气质。

先校正一个关键认知，这是 Astro 的优势，不是限制。

Astro 不是“基于 Vue 的博客”，而是： 👉 Astro = 静态站框架 + 可按需引入 Vue 组件

Chatgpt给我选了Tailwind CSS，并且推荐我选择一套 **耐看、长期不腻、非常“专业”**的风格，我觉得他是对的，目前这种风格我老了可能也希望（不过我老了还会是二次元吗）。您可以点击我设置的Tailwind的超链接，来看看里面的组件是否对您的胃口。

目前我还是希望引入一个组件进行开发先，这样可以避免复杂性，少即是多。

开发环境

我选用的是用Vs Code作为我的文本编辑器进行开发，并且已经安装了Astro的拓展。

note

Node.js - v18.20.8 或 v20.3.0、v22.0.0 或更高版本。（v19 和 v21 均不支持。）

Astro 使用 Vite 构建，Vite 默认针对支持现代 JavaScript 的浏览器。要阅读完整的参考，你可以在 Vite 中查看当前支持的浏览器版本列表。

终端 - Astro 通过其命令行界面（CLI）访问。

先让 AI Code 帮你搭一版骨架

当你已经确定了需求和技术路线，其实可以把 AI 当成“脚手架助手”，先让它帮你搭一个能跑起来的版本。
我自己的习惯是：先让 AI 快速出一版，再人工做第二轮收敛。这样做效率会高很多，也更不容易卡在第一步。

一套我自己会用的提示词（可直接复制）

你可以把下面这段贴给 AI（ChatGPT、Codex、Cursor 都可以）：

你是一个资深前端工程师，请帮我从 0 到 1 搭建一个 Astro 个人博客项目。

我的目标：
1) 技术栈：Astro + Tailwind CSS
2) 文章：Markdown 写作
3) 部署：GitHub Pages
4) 要求：适合新手维护，目录结构清晰，样式简洁克制

请按下面方式输出：
1) 先给我项目目录结构（树形）
2) 再给我需要执行的命令（按顺序）
3) 再给我每个关键文件的完整内容（astro.config.mjs、package.json、基础页面、博客内容目录）
4) 每一步都注明“为什么要这样做”
5) 最后给我一份排错清单（常见报错 + 解决办法）

约束：
- 不要跳步
- 不要省略关键配置
- 所有命令可直接复制
- 优先给稳定方案，不要花哨技巧

第二轮提示词（让 AI 改，而不是重写）

第一版跑起来后，你再给 AI 这个指令：

下面是我当前项目状态，请你只在现有结构上增量修改，不要推翻重来。

目标：
1) 保持现有路由不变
2) 优化首页排版和博客列表样式
3) 增加 tags 页面
4) 确保 npm run build 通过

输出要求：
1) 只给“需要修改的文件”
2) 每个文件给最小改动 diff
3) 改动后附上验证命令

这类“增量修改”提示词很关键，不然 AI 很容易把你已经写好的内容一锅端掉。举个例子，这就是我确定好需求后直接让codex帮我大体改出来的效果。很适合项目起步，后续如果您调试的时候自己没头绪，也可以让ai写一份专业的提示词，这样比你说这个东西应该在那个东西的左边右边更加合理，毕竟aicode他看不见嘛，他是个很聪明的盲人。

安装

安装node.js（Windows安装）

Node.js 安装包及源码下载地址为：https://nodejs.org/en/download。

最简单的办法，点开网址，然后点击按钮Windows Installer(.msi)，当然我也给你做好了超链接，你点一下能下载了。

安装步骤

双击安装包
点击以上的 Next 按钮
勾选接受协议选项，点击 Next 按钮 :
Node.js默认安装目录为 “C:\Program Files\nodejs” , 你可以修改目录，并点击 Next 按钮：
点击 Install（安装）开始安装 Node.js，你也可以点击 Back（返回）来修改先前的配置：
安装完后点击 Finish（完成）按钮退出安装向导。

tip

安装完成后，我们可以在命令行或 Windows Powershell 中执行以下命令来测试。这是输出node版本号的命令，如果正常输出，则表示安装成功。

至于命令行怎么调用出来，最简单的就是Win+R，然后输入cmd，回车。

node -v
npm -v

#example
C:\Users\Dan>node -v
v24.13.0

如果你遇到网络问题（下载慢 / 安装依赖超时）

很多新手第一次卡住都在这里，不是你操作错了，通常是网络到 npm 官方源太慢。
可以先把 npm 源切到国内镜像，再继续安装依赖：

# 查看当前源
npm config get registry

# 切换到国内镜像（npmmirror）
npm config set registry https://registry.npmmirror.com

# 再确认一下
npm config get registry

然后再执行：

npm install

如果你后面想切回官方源，也很简单：

npm config set registry https://registry.npmjs.org

安装Vs Code

你可以直接去官网下载安装（推荐 Stable 版本）：

https://code.visualstudio.com/

简版步骤（Windows）：

打开官网，点击 Download for Windows。
双击安装包，基本一路 Next 就行。
建议勾选这几个选项：
Add "Open with Code"、Add to PATH、Register Code as an editor。
安装完成后，打开 VS Code，File -> Open Folder 选择你的博客项目目录。
打开终端（Ctrl + ~），执行：

npm -v
node -v

能看到版本号就说明开发环境已经通了。

我自己常用的扩展（够用版）：

Astro（官方语法支持）
Tailwind CSS IntelliSense（Tailwind 类名提示）
Markdown All in One（写 Markdown 更顺手）

如果您对上手编程感兴趣，我会在日后更新的文章《如何上手编程》中详细说明更多。

安装Astro

我这边还是建议提供通过 CLI 向导安装，

1.在终端运行以下命令，首先我建议你选好文件夹，我的话是F:\project\Blog，你在文件资源管理器里打开至当前文件夹，然后点击搜索左边的路径，然后输出cmd，回车。安装下面的步骤来，您可以按照格式输入您的项目名称，选择Use blog template。

# 使用 npm 创建一个新项目
npm create astro@latest

2.项目创建好后，也就是当你的可以输入了，例如出现了例如，这边有个光标一直在闪

C:\Users\Dan>

3.接下来你cd进你的项目，例如我的项目文件夹叫做astro-blog，所以我在命令行内输入。cd进入对应文件夹后就安装依赖就行了，大概率不需要换源，既然您能看到我的博客网站了，那您的网络环境应该是满足条件的。

F:\project\Blog>cd astro-blog

F:\project\Blog\astro-blog>npm install

到这里其实本地就能跑起来了，你可以先试一下：

npm run dev

浏览器打开 http://localhost:4321/，看到页面正常就可以进入下一步了。

部署到 GitHub Pages

先准备账号和工具（新手建议按顺序来）

1. 注册 GitHub 账号

打开 https://github.com/。
点击右上角 Sign up。
输入邮箱、密码和用户名（用户名后面会出现在你的博客网址里）。
按提示做人机验证，完成邮箱验证。
登录后先记住你的用户名，后面要填到仓库地址和 site 配置里。

tip

如果你后面想长期维护项目，建议在 Settings 里把 2FA（两步验证）开一下，账号更安全。

2. 安装 Git（Windows）

打开官网 https://git-scm.com/downloads 下载 Windows 安装包。
双击安装，绝大多数选项保持默认即可，一路 Next。
安装完成后，打开 cmd 或 PowerShell，执行：

git --version

看到版本号就说明安装成功。然后配置你的身份信息（只需配置一次）：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

3. 安装 GitHub Desktop（可选，但对新手非常友好）

如果你不想一上来就记太多命令，GitHub Desktop 是个很好的过渡工具。

下载并安装：https://desktop.github.com/
打开后登录你的 GitHub 账号。
File -> Add local repository...，选择你的项目目录。
修改代码后，在左侧看变更，填 Summary，点击 Commit to main。
点击右上角 Push origin，把提交推送到 GitHub。

我自己日常还是命令行为主，但给刚入门的同学，我通常先推荐 Desktop，心理负担会小很多。坐上轮椅是对的，你想你不应该有什么心里负担，又没人会说你 skill issue这类的话，提升效率是第一原则，你应该专心commit，然后push，怎么方便怎么来。

初始化仓库并首次推送（CLI / Desktop 二选一）

如果你是第一次做这个项目，可以按下面这套来（已经有仓库的就跳过）：

先在 GitHub 网页里创建一个空仓库，然后把仓库地址替换到下面命令里。

方案A：命令行（CLI）

git init
git add .
git commit -m "init astro blog"
git branch -M main
git remote add origin https://github.com/<你的GitHub用户名>/<你的仓库名>.git
git push -u origin main

方案B：GitHub Desktop（图形界面）

在 GitHub Desktop 里 Add local repository 选择你的项目目录。
首次提交填一个说明，例如 init astro blog。
点击 Publish repository，输入仓库名并发布到 GitHub。
以后每次更新就是 Commit + Push origin。

我自己的建议是仓库名尽量简单一点，全小写，后续配置 base 的时候不容易输错。

参考我的博客项目：先 clone 再改成你自己的

如果你是想直接参考我这套项目结构来学习，最快方式就是先把我的仓库 clone 到本地：

git clone https://github.com/Dancncn/DansBlog.git
cd DansBlog
npm install
npm run dev

本地跑起来后，你会在 http://localhost:4321/ 看到完整博客。

项目地址也放在这里，方便你直接点开：

https://github.com/Dancncn/DansBlog

如果这篇教程或这个项目对你有帮助，欢迎顺手点个 Star，这对我真的很有鼓励作用。

接着你要把它改成你自己的仓库，流程如下：

在你自己的 GitHub 账号下新建一个空仓库（例如 my-blog）。
修改 astro.config.mjs 里的这两项：
site: 'https://<你的用户名>.github.io'
base: '/<你的仓库名>/'
把远程地址改成你自己的：

git remote set-url origin https://github.com/<你的用户名>/<你的仓库名>.git
git push -u origin main

到 GitHub 仓库 Settings -> Pages，把 Source 设为 GitHub Actions。
等待 Actions 跑完，你就可以通过： https://<你的用户名>.github.io/<你的仓库名>/ 访问到你自己的博客。

配置 Astro 的 site 和 base（这一步很关键）

如果你部署的是项目仓库（例如 https://<用户名>.github.io/<仓库名>/），Astro 里一定要配 base，不然静态资源路径很容易 404。

astro.config.mjs 可以像这样：

const REPO_BASE = '/<你的仓库名>/';

export default defineConfig({
  site: 'https://<你的GitHub用户名>.github.io',
  base: REPO_BASE,
  trailingSlash: 'always',
  output: 'static',
});

如果你用的是用户主页仓库（仓库名就是 <用户名>.github.io），那通常 base 可以写 /。

用 GitHub Actions 自动部署

我个人比较喜欢自动化，push 一次就发布一次，省心很多。
在项目里新建文件：.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - uses: actions/configure-pages@v5
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

你如果是直接用 Astro 的 blog 模板，很多时候这份文件本来就有，可以先看一眼再决定要不要改。

打开 GitHub Pages

进入你的仓库，点击 Settings。
左侧找到 Pages。
Source 选择 GitHub Actions。
回到 Actions 页面等工作流跑完。

跑完后一般就能在下面这个地址看到你的网站：

https://<你的GitHub用户名>.github.io/<你的仓库名>/

我自己踩过的几个坑

页面能打开，但 CSS 全丢了：base 配错了。
图片 404：Markdown 里图片路径写错，尽量用相对路径。
Action 失败：看日志通常就是依赖没装好或者 Node 版本不对。
刚部署访问 404：等 1-2 分钟，GitHub Pages 有时候会慢一点。
代码推上去了但页面没更新：你可能推到了别的分支，不是 main。
本地能跑，线上白屏：site 和 base 组合不对，静态资源路径全偏了。
用中文路径或带空格路径建项目：某些脚本在 Windows 下容易出玄学问题，建议英文目录。
npm install 很慢甚至卡死：先检查网络，再考虑换镜像源，不要一上来就怀疑项目坏了。
改完配置忘记重启 dev server：有些配置（比如 astro.config.mjs）必须重启才生效。
图片文件名随手改大小写：Windows 不敏感、GitHub Pages（Linux）敏感，最后线上 404。
直接在 GitHub 网页端乱改配置文件：很容易和本地冲突，最好本地改完再统一 push。

部署到 Cloudflare Pages（推荐：更强 CDN + 更少运维）

如果你已经把 GitHub Pages 跑通了，这一节可以看成“同一个 Astro 项目，换一条更省心的发布链路”。我自己后来长期用下来，Cloudflare Pages 在部署体验和可维护性上都更顺手。

为什么考虑 Cloudflare Pages（对比 GitHub Pages）

全球 CDN：静态资源分发节点更多，国际访问通常更稳。
自动 HTTPS：默认证书和 TLS 配置都省掉了。
自动构建部署：连好仓库后，每次 push 自动构建上线。
性能与安全：缓存、压缩、基础安全策略都比较完善。
未来可扩展：后面要接 Functions/Workers，或者用 D1/KV/R2，也能在同一生态里继续长。

对可访问性这件事我说结论：国际访问通常会显著更好；中国大陆地区通常也比 GitHub Pages 更“可用”，但它不是“国内 CDN 同等级稳定性”的承诺，这两件事要分开看。

从 0 开始部署步骤（注册到上线）

注册并登录 Cloudflare，进入 Dashboard。
在左侧菜单进入 Workers & Pages。
选择 Pages。如果你看到新版界面，入口可能在 Looking to deploy Pages? Get started 这类提示里。
点击 Import an existing Git repository，按提示连接 GitHub，授权后选择你的博客仓库。
在 Build settings 里填这四个关键项：
- Framework preset: Astro
- Build command: npm run build
- Build output directory: dist
- Production branch: main
点击部署，等构建完成后先用 xxx.pages.dev 域名访问。

第一次部署建议先别急着绑定自定义域名，先把默认域名验收跑通，排错成本最低。对于域名购买以及配置教程，请参考如何注册一个cloudflare域名，附带视频教程。

必踩坑：base 路径导致样式丢失（以及如何修）

最常见现象是：页面能打开，但样式全没了，像一页蓝色链接的纯 HTML。根因通常是你之前给 GitHub Pages 写死了 base: '/DansBlog/'，Cloudflare 继续用这套路径后，资源地址就错了。

astro.config.mjs 推荐改成按环境自动切换：

import { defineConfig } from 'astro/config';

const isCfPages = process.env.CF_PAGES === '1';
const isGithubProd = !isCfPages && process.env.NODE_ENV === 'production';

const base = isCfPages ? '/' : isGithubProd ? '/DansBlog/' : '/';

export default defineConfig({
  site: 'https://your-domain-or-pages-domain',
  base,
  trailingSlash: 'always',
  output: 'static',
});

这段配置对应的行为是：

Cloudflare 构建（CF_PAGES=1）：base = '/'
GitHub Pages 生产构建：base = '/DansBlog/'
本地 npm run dev：base = '/'

再补一个习惯：页面里尽量不要写死 "/DansBlog" 这类前缀，优先用 import.meta.env.BASE_URL 或相对路径，不然后面平台一换就炸。

验收方法（本地模拟 + 线上检查）

先在本地模拟 Cloudflare 构建（Windows CMD）：

set CF_PAGES=1
npm run build
npx astro preview

然后访问本地预览地址，检查首页和文章页是否正常加载样式。

可选：再模拟 GitHub Pages 生产构建（Windows CMD）：

set CF_PAGES=
set NODE_ENV=production
npm run build
npx astro preview

然后用 http://localhost:4321/DansBlog/ 这类路径做一次回归检查，确认两边都兼容。（PowerShell 可用 $env:CF_PAGES='1' 这种写法，但这里默认按 CMD 流程走。）

线上验收（pages.dev）我会做这几步：

打开首页、文章页、标签页、分页页。
按 F12 打开 DevTools，在 Network 里过滤 404，结果应为 0。
View page source 搜索 "/DansBlog"，Cloudflare 版本里不应该出现。

pages.dev 默认域名与自定义域名

Cloudflare Pages 会给你一个默认免费域名（xxx.pages.dev），这个可以直接用来上线和验收。项目名改变后，子域名前缀通常也会跟着变化。

如果你想用自己的域名，结论也很直接：通常需要先有自己的域名，然后在 Pages 项目里绑定自定义域名。DNS 细节这里不展开，但流程上就是“先买域名，再在 Pages 里绑定”。

面向大陆与国际用户的可达性建议（务实）

这块我不说大话，直接给实操建议：

国际访问：Cloudflare Pages 通常明显优于 GitHub Pages。
大陆访问：通常会比 GitHub Pages 更可用，但它不等同于国内商业 CDN 的稳定性上限。
字体、图片、脚本尽量自托管，减少第三方外链（尤其 Google Fonts 这类跨境依赖）。
静态资源配合 hash 文件名做强缓存，让重复访问更快。
图片优先走你自己的站点资源；如果后面有对象存储需求，可以考虑接 R2。

小结

到这一步其实你已经完成了一套很实用的流程：本地写作 -> git push -> GitHub 自动构建并发布。
后面你要做的就是持续写内容，然后慢慢把样式打磨成你喜欢的样子。
技术是骨架，内容才是灵魂。先让它跑起来，再让它变好看。

我希望您可以没有心理负担，可以尝试使用aicode来协助您的工作，这对您的工作效率大大的提升，比方说本站我第一天只用了4小时就实现了基本的Home，blog，about页面可以拿来展示了，第二第三天则是花费一些时间进行精修和移动端适配。但不要忘了自己做博客网站的初心，一切目的以实现博客正常发布阅读功能为主，增加其他花样功能则是自己的情趣，愿不愿意在下面折腾时看你自己。

How to Build a Personal Blog Website

Thu, 12 Feb 2026 00:00:00 GMT

Preface

When I realized I was remembering less and less of my technical ideas, I started writing things down in my phone notes during sleepless nights. But phone notes are limited, and I could not access everything smoothly across devices.

In January this year, during another late night, I thought: if I get some time, I should build a personal blog. I want to write down meaningful things for myself, for students I have taught, and maybe for students I will teach in the future.

The problem was: I was very busy. I had just returned from a business trip in Jiangsu. One night, still unable to sleep, I remembered this plan again. It was already very late, so I did not want to disturb friends who had built blogs before. I guessed the whole thing might take around a week.

The next morning, I asked my high school friend Herbert Skyper. His answer: around one week too. He hand-built his version with Vue (no mature blog framework, mostly for frontend fun). When I visited him later, we talked more. Domain cost is usually not expensive per year, but server/public IP/stability are often the annoying parts.

One of the biggest headaches of running a website is exactly this: domain name, reliable always-on machine (or server), public network accessibility, and so on. There are ways to solve all of these, but if you can avoid extra operations in the early stage, that is usually better.

Skyper mentioned some classmates using Astro, which is a mature framework. Later my friend kymi replied too; he writes with Hexo and has a related tutorial: How to Deploy a Blog with Hexo. He also said deployment on GitHub is not too time-consuming, and it avoids server/domain costs at the start.

Requirements Analysis

What exactly do I need?

I need something like a “pro memo” that I can read anytime, and others can read too, without costing too much time or money.

Content comes first, but I also want a little personality in the design. Something simple, rational, and restrained, but still gentle, with small colorful details that can make people smile.

Technical Route

So why did I choose Astro?

I compared several blog frameworks first: their pros, cons, and which one fits me best. Since I have used ChatGPT for years, it has a decent idea of my technical level, and I organized its suggestions into the table below.

Blog Framework Comparison

Framework	Tech Stack	Build Speed	Writing Experience	Component/Interaction Power	Extensibility	GitHub Pages Fit	Best For	Common Pitfalls
Hexo	Node.js	Medium	Easy to start, many themes	Weaker (template-centric)	Medium	Mature and stable	Pure writing, Chinese ecosystem	Node dependencies may be annoying
Hugo	Go	Very fast	Clear structure	Moderate (content-driven)	Medium	Very stable	Speed-focused, low maintenance	Theme config can feel too engineering-ish
Astro	Modern frontend (React/Vue/Svelte)	Fast	Great Markdown/MDX experience	Strong (component mixing)	Strong	Need to handle `base` carefully	Frontend developers	High freedom means more decisions
Next.js / Nuxt	React / Vue full-stack	Medium	Good	Very strong	Very strong	Static export needs prefix care	People planning larger platforms	Slightly heavy for pure blogs
VitePress / Docusaurus	Vite / React	Fast	Excellent for documentation	Medium	Medium	Very stable	Technical docs-style content	Less “blog vibe”
Jekyll	Ruby	Medium	Traditional Markdown	Weaker	Medium	Native support	Minimal deployment overhead seekers	Less modern by today’s standards

Decision-Oriented Summary

Requirement Type	Recommended Option	Why
Pure writing, mature theme ecosystem	Hexo / Hugo	Classic and stable
Lots of technical posts, fastest builds	Hugo	Extremely fast build speed
Blog + project showcase + interactions	Astro	Markdown + components is very strong
Might evolve into personal platform	Next.js / Nuxt	Strong full-stack capability
More documentation-oriented	VitePress / Docusaurus	Great structure and TOC management

ChatGPT told me Astro’s flexibility can feel like a pitfall because you need to make more choices yourself. For me, that is actually an advantage: I can choose the components and style I like.

At first I considered Cloudflare. But once I decided to push the project to GitHub anyway, GitHub Pages became super convenient: configure once, then update via push.

Deployment Cost Snapshot

Item	Reality
Server cost	Usually 0 with GitHub Pages / Cloudflare Pages / Vercel
Domain cost	`username.github.io` is free; custom domains usually cost money
Maintenance overhead	Almost 0 for static sites

Astro supports modern frontend component ecosystems, so which components should you choose?

Your technical route shapes your blog’s personality and tone.

One key mindset correction first: this is Astro’s strength, not a limitation.

Astro is not “a Vue-based blog framework”. It is:

👉 Astro = static-site framework + optional Vue components when needed

ChatGPT recommended Tailwind CSS and suggested a style that is timeless, professional, and easy to live with in the long term. I agree.

At this stage, I still prefer introducing only a small number of components to avoid complexity.

Less is more.

Development Environment

I use VS Code as my text editor, and I installed the Astro extension.

note

Node.js - v18.20.8, v20.3.0, v22.0.0, or higher (v19 and v21 are not supported).

Astro is built with Vite. Vite targets modern JavaScript browsers by default. See the browser support list in Vite docs: Browser Compatibility.

Terminal - Astro is operated via CLI.

Let AI Code Build the First Skeleton for You

Once your requirements and technical direction are clear, you can treat AI as a “scaffolding assistant” and let it create a runnable version first.

My habit is simple: let AI produce a quick first draft, then do a second refinement pass manually. This is much more efficient and helps you avoid getting stuck at step one.

Prompt Set I Actually Use (Copy-Paste Ready)

You can paste this to AI tools like ChatGPT, Codex, or Cursor:

You are a senior frontend engineer. Help me build an Astro personal blog project from 0 to 1.

Goals:
1) Tech stack: Astro + Tailwind CSS
2) Content: Markdown-based writing
3) Deployment: GitHub Pages
4) Requirements: beginner-friendly maintenance, clear project structure, clean and restrained style

Output format:
1) First, provide the project directory tree
2) Then provide commands to run (in order)
3) Then provide full content for key files (astro.config.mjs, package.json, basic pages, blog content dirs)
4) Explain "why" for every step
5) Finally provide a troubleshooting checklist (common errors + fixes)

Constraints:
- Do not skip steps
- Do not omit key configurations
- All commands must be directly runnable
- Prioritize stable solutions over fancy tricks

Second-Round Prompt (Ask AI to Improve, Not Rewrite)

After the first version runs, give AI this:

This is my current project state. Please make incremental changes on top of the existing structure. Do not rewrite from scratch.

Goals:
1) Keep existing routes unchanged
2) Improve homepage layout and blog list style
3) Add tags page
4) Ensure npm run build passes

Output requirements:
1) Only list files that need modification
2) For each file, provide minimal diff
3) Include verification commands after changes

This “incremental modification” style prompt is important. Otherwise AI may accidentally replace things you already wrote.

For example, this is the kind of effect I got when I locked requirements and asked Codex to scaffold it. It is great for getting started. If you feel stuck during debugging, ask AI to help write a precise prompt first. It is often more effective than saying “move this thing a bit left/right.” AI code assistants are smart, but they cannot see your screen.

Installation

Install Node.js (Windows)

Node.js download page: https://nodejs.org/en/download

The simplest way is opening that page and clicking Windows Installer (.msi).

Steps

Double-click the installer.
Click Next.
Accept the license and click Next.
Default path is usually C:\Program Files\nodejs\ (you can change it).
Click Install.
Click Finish when done.

tip

After installation, test Node/NPM in cmd or PowerShell. The fastest way to open cmd: Win + R, type cmd, press Enter.

node -v
npm -v

# example
C:\Users\Dan>node -v
v24.13.0

If Network Is Slow (download/install timeout)

This is a very common beginner issue and not your fault. Often the connection to the official npm registry is simply slow.

You can switch npm registry to a domestic mirror first:

# check current registry
npm config get registry

# switch to npmmirror
npm config set registry https://registry.npmmirror.com

# verify again
npm config get registry

Then run:

npm install

If you want to switch back to the official registry later:

npm config set registry https://registry.npmjs.org

Install VS Code

Download from the official site (Stable recommended):

https://code.visualstudio.com/

Quick Windows setup:

Click Download for Windows.
Run the installer and mostly Next all the way.
Recommended checkboxes: Add "Open with Code", Add to PATH, Register Code as an editor.
Open VS Code, then File -> Open Folder and choose your blog project folder.
Open terminal (Ctrl + ~) and run:

npm -v
node -v

If versions show up correctly, your environment is ready.

Extensions I personally use (minimal but effective):

Astro (official syntax support)
Tailwind CSS IntelliSense (class name suggestions)
Markdown All in One (better Markdown writing flow)

If you are interested in learning programming from scratch, I will publish a future post called “How to Start Programming” with more detailed guidance.

Install Astro

I recommend using the CLI wizard.

Open terminal in your target folder (for me: F:\project\Blog) and run:

# create a new Astro project
npm create astro@latest

Choose your project name and select Use blog template.

After project creation, when terminal is ready again (cursor blinking), continue.

C:\Users\Dan>

Enter your project folder and install dependencies:

F:\project\Blog>cd astro-blog
F:\project\Blog\astro-blog>npm install

At this point, the local site should already run:

npm run dev

Open http://localhost:4321/ in browser. If it looks normal, move on.

Deploy to GitHub Pages

Prepare Accounts and Tools First (Beginner-Friendly Order)

1. Create a GitHub Account

Open https://github.com/.
Click Sign up.
Enter email, password, and username (username appears in your blog URL).
Finish verification and email confirmation.
Remember your username, you will use it in repo URL and Astro site config.

tip

If you plan long-term maintenance, enable 2FA in Settings for better account safety.

2. Install Git (Windows)

Download from https://git-scm.com/downloads.
Run installer; default options are usually fine.
Verify in terminal:

git --version

Then configure identity (one-time):

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

3. Install GitHub Desktop (Optional, very beginner-friendly)

If you do not want to memorize many commands at first, GitHub Desktop is a great bridge.

Download: https://desktop.github.com/
Sign in with your GitHub account.
File -> Add local repository..., choose your project folder.
After edits, review changes, write a Summary, click Commit to main.
Click Push origin to upload.

I still use CLI in daily work, but for beginners I often recommend Desktop first. No mental burden needed. Efficiency matters: commit, push, and move forward.

Initialize Repository and First Push (CLI / Desktop)

If this is your first time, follow this flow (skip if repo already exists).

Create an empty repository on GitHub first, then replace the URL below.

Option A: CLI

git init
git add .
git commit -m "init astro blog"
git branch -M main
git remote add origin https://github.com/<your-github-username>/<your-repo-name>.git
git push -u origin main

Option B: GitHub Desktop (GUI)

In GitHub Desktop, Add local repository.
For first commit, use a message like init astro blog.
Click Publish repository.
Next updates are simply Commit + Push origin.

My recommendation: keep repository name simple and lowercase, which helps avoid mistakes when configuring base later.

Use My Blog Project as a Reference: Clone First, Then Customize

If you want to learn from my current project structure directly, quickest way:

git clone https://github.com/Dancncn/DansBlog.git
cd DansBlog
npm install
npm run dev

After local startup, open http://localhost:4321/.

Project link:

https://github.com/Dancncn/DansBlog

If this tutorial or project helps you, I would really appreciate a Star on the repo.

Then convert it to your own repo:

Create a new empty repository in your own GitHub account (for example my-blog).
Update these fields in astro.config.mjs: site: 'https://<your-username>.github.io' base: '/<your-repo-name>/'
Replace remote URL:

git remote set-url origin https://github.com/<your-username>/<your-repo-name>.git
git push -u origin main

Go to Settings -> Pages and set Source to GitHub Actions.
Wait until Actions finishes, then visit: https://<your-username>.github.io/<your-repo-name>/

Configure `site` and `base` in Astro (Critical)

If you deploy as a project repo (for example https://<username>.github.io/<repo>/), you must configure base, otherwise static assets often return 404.

astro.config.mjs example:

const REPO_BASE = '/<your-repo-name>/';

export default defineConfig({
  site: 'https://<your-github-username>.github.io',
  base: REPO_BASE,
  trailingSlash: 'always',
  output: 'static',
});

If you use a user-site repo (<username>.github.io), base is usually /.

Auto Deploy with GitHub Actions

I personally prefer automation: one push, one deployment.

Create file: .github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - uses: actions/configure-pages@v5
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

If you started from Astro’s blog template, this file may already exist. Check first before editing.

Enable GitHub Pages

Open your repo, click Settings.
Find Pages in left sidebar.
Set Source to GitHub Actions.
Go back to Actions and wait for workflow success.

After that, your site is usually available at:

https://<your-github-username>.github.io/<your-repo-name>/

Pitfalls I Personally Hit

Site opens but CSS is missing: base is wrong.
Images 404: wrong Markdown image path, prefer relative paths.
Action failed: most often dependency install or Node version issue.
Fresh deployment still 404: wait 1-2 minutes; Pages can lag.
Pushed code but site did not update: likely pushed to wrong branch (not main).
Works locally, white screen online: site + base combination is wrong.
Project path with Chinese chars/spaces: can trigger weird script issues on Windows.
npm install is very slow/stuck: check network first, then switch registry.
Changed config but no effect: some files (like astro.config.mjs) require dev server restart.
Random file-name case changes: Windows is case-insensitive, Linux (Pages) is not, causing online 404.
Editing config directly on GitHub web too often: easy to conflict with local changes.

Deploying to Cloudflare Pages (Recommended: Stronger CDN & Less Maintenance)

If GitHub Pages is already working for you, this is a practical upgrade path worth trying. In real-world use, Cloudflare Pages usually gives you a smoother deployment loop and stronger global delivery out of the box.

Why Consider Cloudflare Pages?

Global CDN: static assets are distributed closer to visitors worldwide.
Automatic HTTPS: certificate and TLS are managed for you.
Automatic deployment from Git: push to branch, trigger build, ship.
Performance and basic security benefits: caching, compression, and edge protection are easier to get right.
Future scalability: you can extend with Pages Functions / Workers and pair with D1 / KV / R2 when needed.

For access quality, keep expectations realistic: international performance is usually excellent; mainland China is often more usable than GitHub Pages, but this is still not the same as a mainland CDN setup with ICP filing.

Step-by-Step Deployment Guide

Create a Cloudflare account and enter the dashboard.
In the left menu, open Workers & Pages.
Choose Pages. In the newer UI, this entry may appear under Looking to deploy Pages? Get started.
Click Import an existing Git repository.
Connect your GitHub account and select your blog repository.
Configure build settings:
- Framework preset: Astro
- Build command: npm run build
- Build output directory: dist
- Production branch: main
Start deployment. After success, open the generated *.pages.dev URL.

My recommendation: validate everything on the default pages.dev domain first, then bind custom domain later.

The Most Common Pitfall: Base Path Issues

This is the one that gets almost everyone once.

GitHub Pages project sites usually live under a subpath like /DansBlog/.
Cloudflare Pages usually serves your site from root path /.
If base still points to /DansBlog/, your page loads as blue links / raw HTML with missing CSS/JS.

Use an environment-based base switch in astro.config.mjs:

import { defineConfig } from 'astro/config';

const isCfPages = process.env.CF_PAGES === '1';
const isGithubProd = !isCfPages && process.env.NODE_ENV === 'production';

const base = isCfPages ? '/' : isGithubProd ? '/DansBlog/' : '/';

export default defineConfig({
  site: 'https://your-domain-or-pages-domain',
  base,
  trailingSlash: 'always',
  output: 'static',
});

Behavior of this setup:

Cloudflare build: base = "/"
GitHub Pages production build: base = "/DansBlog/"
Local dev: base = "/"

Also avoid hardcoded "/DansBlog" in links/components. Prefer import.meta.env.BASE_URL or relative paths.

How to Validate the Deployment

Local simulation first (Windows CMD):

set CF_PAGES=1
npm run build
npx astro preview

Optional PowerShell equivalent:

$env:CF_PAGES='1'
npm run build
npx astro preview

Online validation checklist:

Open your pages.dev URL.
Open DevTools -> Network, confirm 404 count is 0.
View page source and search for "/DansBlog"; it should not appear in Cloudflare deployment output.
Test key routes: home page, article page, tag page, pagination.

pages.dev Domain & Custom Domain

pages.dev is the default free subdomain.
Renaming the project usually changes the subdomain prefix.
If you want your own domain, you usually need to purchase one first.
Cloudflare Pages supports custom domain binding directly in project settings.
Regarding domain acquisition and setup, please consult the guide on How to Register a Cloudflare Domain, which includes a video tutorial.

Accessibility for International & Mainland China Users

Practical expectations:

International visitors: usually very strong performance.
Mainland China users: often more usable than GitHub Pages.
Without ICP备案 and mainland CDN architecture, do not expect domestic-CDN-level stability everywhere.

Low-cost improvements that help a lot:

Self-host fonts instead of relying on Google Fonts.
Minimize third-party external scripts.
Leverage static asset caching (hashed file names + long cache headers).

Wrap-up

By now you already have a very practical workflow: local writing -> git push -> GitHub auto build + deploy.

From here, keep writing and gradually polish your style. Technology is the skeleton; content is the soul. First make it run, then make it beautiful.

I hope you can use AI code tools without psychological pressure. They can significantly improve productivity. For example, this site reached a usable Home/Blog/About structure in about 4 hours on day one, then I spent day two and day three refining details and mobile adaptation.

But do not forget your original goal for building a blog: reliable publishing and reading comes first. Fancy features are optional personal fun. Add them if you want, skip them if you do not.

GoFile 下载工具 -- 完整使用指南

Wed, 11 Feb 2026 00:00:00 GMT

引言

说实话，Gofile这个网盘使用起来还是还是有点麻烦的，比方说有你需要下载的资源的时候。欸，让你等等再下载，但是你很急，又不想开会员，那就可以试试这个小工具了，如果你不知道你要下的对应链接里的对应文件的下载命令怎么写，也不妨让ai来帮你吧，坐上轮椅是对的。

1. 获取项目

项目托管在 GitHub：

https://github.com/rkwyu/gofile-dl

你可以通过两种方式获取它。

方法 1 — 下载 ZIP（推荐）

打开仓库页面
点击 Code
选择 Download ZIP
解压到任意文件夹

方法 2 — 使用 Git 克隆

如果已安装 Git：

git clone https://github.com/rkwyu/gofile-dl

2. 安装依赖

打开项目文件夹。

点击地址栏，输入：

cmd

按下回车。

然后安装依赖：

python -m pip install -r requirements.txt

等待安装完成。

如果无法识别 Python：

python --version

请重新安装 Python 并启用：

将 Python 添加到 PATH

3. 运行下载器

执行：

python run.py -i "output_filename.zip" https://gofile.io/d/your_link_id

示例：

python run.py -i "example.zip" https://gofile.io/d/abcd1234

下载后的文件会出现在：

outputs/

4. 常见问题

找不到 Python

重新安装 Python，并正确配置 PATH。

pip 安装报错

python -m pip install --upgrade pip

流程总结

获取仓库
安装依赖
运行下载命令

完成。

说明

此工具仅用于下载可公开访问的文件。
请确保遵守适用法律及平台服务条款。

GoFile Download Tool -- Complete Usage Guide

Wed, 11 Feb 2026 00:00:00 GMT

1. Getting the Project

The project is hosted on GitHub:

https://github.com/rkwyu/gofile-dl

You have two ways to obtain it.

Method 1 — Download ZIP (Recommended)

Open the repository page
Click Code
Select Download ZIP
Extract it to any folder

Method 2 — Clone via Git

If Git is installed:

git clone https://github.com/rkwyu/gofile-dl

2. Install Dependencies

Open the project folder.

Click the address bar, type:

cmd

Press Enter.

Then install dependencies:

python -m pip install -r requirements.txt

Wait until installation finishes.

If Python is not recognized:

python --version

Reinstall Python and enable:

Add Python to PATH

3. Run the Downloader

Execute:

python run.py -i "output_filename.zip" https://gofile.io/d/your_link_id

Example:

python run.py -i "example.zip" https://gofile.io/d/abcd1234

Downloaded files will appear in:

outputs/

4. Common Issues

Python Not Found

Reinstall Python and configure PATH properly.

pip Installation Errors

python -m pip install --upgrade pip

Workflow Summary

Get repository
Install dependencies
Run download command

That’s all.

Notes

This tool is intended for downloading publicly accessible files.
Ensure you comply with applicable laws and platform terms of service.