最本质的区别在于它们运行的对象不同：

1. QEMU（软件仿真）：运行的是“行为模型”。

   • 原理： QEMU 是一个纯软件程序，运行在通用的服务器（x86 架构）上。它不关心芯片内部具体的电路是怎么连的，它只关心功能。
   • 比喻： 就像你在电脑上玩“超级马里奥”模拟器。电脑并不含有任天堂的游戏机电路，它只是用软件模拟了“按 A 键跳跃”这个行为。
   • 关键词： 功能级（Functional）。它知道“CPU 写了这个寄存器，灯就会亮”，但它不在乎电流是怎么流过去的。

2. Palladium / ZeBu / HAPS（硬件仿真/原型）：运行的是“RTL 电路”。

   • 原理： 这些机器内部塞满了大量的专用芯片（FPGA 或 定制处理器）。我们将芯片设计的源代码（RTL） 综合成电路网表，真刀真枪地烧录或者映射到这些机器里运行。
   • 比喻： 这就像是用乐高积木（FPGA/专用芯片）按照设计图纸，1:1 搭建了一个巨大的、虽然跑得慢但结构完全真实的“游戏机”。
   • 关键词： 周期级（Cycle-accurate）。它精确地模拟了每一个时钟周期内，信号在电线上的翻转。

三大维度深度对比

为了方便理解，我将对比分为三个维度：速度、真实度（精度）、可观测性。

速度 (Speed)

• QEMU： 极快。
  • 因为它跳过了复杂的电路细节，直接用主机 CPU 指令模拟目标指令，速度可以达到数百 MIPS（每秒百万条指令）。
  • 用途：适合你们软件团队开发上层应用、操作系统（Linux/Android）启动、UI 交互。
• HAPS (FPGA Prototyping)： 较快。
  • 它通常能跑到 5MHz - 100MHz。虽然比真实芯片（几 GHz）慢，但比下面的 Emulation 快。
  • 用途：适合驱动开发、长时间的压力测试、视频编解码测试。
• Palladium / ZeBu (Emulation)： 较慢。
  • 通常在 500kHz - 2MHz 左右。启动一个 Android 可能需要几小时（虽然现在有混合模式加速，但纯硬件部分依然慢）。
  • 用途：芯片逻辑除错、极早期的驱动验证。

真实度/精度 (Accuracy) —— 这是最关键的区别

• QEMU： 时序是假的。
  • 在 QEMU 里，你写一个指令 Delay(1ms)，它可能并不真的精确对应硬件的多少个时钟周期。它往往假设总线交互是瞬间完成的。
  • 风险：它测不出竞争冒险（Race Condition）或者带宽瓶颈。
• 硬件平台 (Palladium/ZeBu/HAPS)： 时序是真的。
  • 它严格遵守电路设计的时序。如果你的代码需要等待硬件模块响应，而那个模块需要耗费 100 个时钟周期才能把数据准备好，硬件平台就会真的让你等 100 个周期。

可观测性 (Visibility) —— 也就是 Debug 的难度

• QEMU： 你只能看到 CPU 寄存器、内存和你在代码里打印的 Log。你看不到芯片内部的一根“电线”是高电平还是低电平。
• Palladium / ZeBu： 上帝视角。
  • 我可以随时“暂停”时间，查看芯片内部几十亿个晶体管中任意一个的状态，甚至可以回放（Waveform dumping）。这对于查硬件 Bug 是救命的。
• HAPS： 比较难查。因为它为了追求速度，牺牲了可观测性。通常需要预埋一些探针才能看波形。

实战拆解：一个“简单”的 DMA 搬运，在不同平台的表现

光讲理论太枯燥，我们用一个经典的 “CPU 指挥 DMA 搬数据” 的例子，来看看 QEMU 是怎么“欺骗”你的，而硬件仿真平台又是如何工作的。

DMA 搬运一搬可以分为下面几步：

1. CPU 往内存写一段数据。
2. CPU 配置 DMA，把这段数据搬到另一个地方。
3. DMA 搬完后，发一个中断告诉 CPU：“我干完了”。

在 QEMU 里的美好世界

在 QEMU 的代码里，DMA 设备通常是一个 C++ 类。当你写入“开始”寄存器时，QEMU 内部可能就直接调用了一个 memcpy() 函数。

• 总线拥堵？ 不存在的，QEMU 里内存读写瞬间完成。
• 缓存同步？ 没关系的，QEMU 往往默认 CPU 和 DMA 看到的是同一块内存，不需要你操心 Cache 一致性。
• 结果： 代码逻辑通顺，中断准时到达，数据完美无缺。你觉得你的驱动无懈可击。

在硬件仿真平台（真实电路）里的残酷真相

当你把同一段代码放到 Palladium 上（这里跑的是真实的芯片电路设计图），情况完全变了。

总线上的“堵车”事故（AXI 背压）

• QEMU: 一路畅通。
• 硬件真相： DMA 发出写请求，但此时内存控制器正忙着处理 GPU 的请求，于是回了一个 Wait 信号。如果你的 DMA 硬件设计在处理这个 Wait 信号时状态机写得有问题，它可能就卡死在这里，傻等着永远不会来的“通行证”。
• 后果： 死锁。软件一直在等中断，但中断永远不会来。

缓存里的“谎言” (Cache Coherency)

• QEMU: CPU 写完数据，DMA 立刻就能读到最新的。
• 硬件真相： CPU 写的数据还在 CPU 的 L1 Cache 里，还没来得及写到 DDR 内存条上。此时 DMA 去读内存，读到的是旧数据（全是 0）。
• 后果： 数据校验错误。这是最坑的，因为系统没挂，但数据是错的，且极难复现。

中断的“生死时速” (Race Condition)

• QEMU: 逻辑上的先后顺序，先发中断，再处理。
• 硬件真相： DMA 拉高中断线需要 1 个时钟周期，信号经过总线传到 CPU 需要 10 个周期。就在这几纳秒的时间差里，如果你的驱动程序刚好去操作了清除中断的寄存器，或者总线出现了乱序。
• 后果： 丢中断。DMA 觉得我发了，CPU 觉得我没收到，两人面面相觑。

既然 QEMU 这么多坑，为什么还要用？

硬件仿真平台（Palladium/ZeBu）虽然真实，但也有致命缺点：贵、慢、难伺候。

• 它启动一次 Linux 可能要几个小时（QEMU 只要几秒）。
• 想加个断点调试？流程极其繁琐。
• 机器非常昂贵，通常全公司也没几台，得排队用。

最佳实践：软硬结合的“三步走”

作为一名聪明的开发者，你应该清楚每种工具的定位：

1. 早期开发 (QEMU): 这里的目的是跑通软件逻辑。验证任务调度、UI 交互、驱动的基本状态机。只要 QEMU 跑通了，说明你的代码逻辑大体是对的。
2. 中期验证 (硬件仿真/FPGA): 代码逻辑没问题了，现在要验证时序和硬件交互。把代码放到 Palladium 或 FPGA 上跑。这时候你会遇到上面说的死锁、数据错、超时。别慌，这正是硬件仿真平台的价值所在——帮你在流片前把这些深层 Bug 挖出来。
3. 最终回流: 当你在硬件平台上修复了 Bug（比如加了内存屏障指令），记得把这些改动同步回 QEMU 仓库，虽然 QEMU 不需要它也能跑，但保持代码一致性很重要。

硬件三巨头

同样作为硬件仿真平台，Palladium、ZeBu、HAPS 之间也有一些区别：

1. Palladium (Cadence 公司) / ZeBu (Synopsys 公司)：
   • 学名： 硬件仿真器 (Emulator)。
   • 特点： 极贵（一台机器几千万甚至上亿人民币）。编译代码很快，Debug 能力最强。
   • 你的用法： 芯片设计早期（RTL 刚写好），如果你的固件跑挂了，你需要找硬件设计人员看波形，这时候用这个。
2. HAPS (Synopsys 公司)：
   • 学名： FPGA 原型验证系统 (FPGA Prototyping)。
   • 特点： 也就是很多块高性能 FPGA 连在一起。跑得比 Emulator 快很多。
   • 你的用法： 芯片设计中后期。主要用来给你做驱动开发、跑真实的操作系统。因为它跑得够快，你能感觉到系统的流畅度。

附录：术语表

• RTL (Register Transfer Level)： 寄存器传输级代码。这是硬件工程师写的代码（通常用 Verilog 或 VHDL 语言）。它是芯片设计的“源代码”。QEMU 不跑这个，硬件仿真平台跑这个。
• 流片 (Tape-out)： 指芯片设计完成，把设计数据发送给晶圆厂（如台积电）进行制造的过程。流片极其昂贵，一旦失败损失巨大，所以必须在流片前用仿真平台测准。
• FPGA (Field-Programmable Gate Array)： 现场可编程门阵列。一种“万能芯片”。你可以通过编程改变它内部的电路连接。我们用它来模拟还没造出来的 ASIC 芯片。
• 时钟周期 (Clock Cycle)： 芯片心脏跳动一次的时间。2GHz 的 CPU，一个周期就是 0.5 纳秒。硬件仿真就是精确模拟每一次跳动发生了什么。
• 网表 (Netlist)： 类似于软件编译后的“汇编语言”或二进制。RTL 代码经过“综合（Synthesis）”工具处理后，就变成了由门电路（与门、非门、触发器）组成的网表。
• 时钟域 (Clock Domain)： 芯片里不同模块跑的速度不一样（比如 CPU 跑 2G，USB 模块跑 100M）。信号从 2G 传到 100M 的区域，需要特殊的同步处理，这往往是 Bug 的高发区。

我一直挺喜欢骑车。骑久了就绕不开一个现实问题：什么时候该补？补多少？补完有没有用？

过去我都是凭感觉——饿了、腿软了、想吃甜的了就来一口。但越骑越久，我开始好奇：所谓“补能量”，到底是在干嘛？说白了很多时候就是在把血糖拉起来。那问题来了：

我在骑行中，究竟什么时候真的需要“抬血糖”？

半年前，我干了件有点“自虐式认真”的事：给自己买了一个动态血糖仪（CGM），准备把“凭感觉补给”变成“看数据补给”。

最初的计划：用血糖曲线给能量胶打分

CGM 最大的魅力是：你能直观看到“吃进去的碳水”对血糖造成的变化。于是我很自然地把好奇心转向了能量胶：

• 不同品牌的胶，升糖速度一样吗？
• 峰值谁更高？
• 谁能撑得更久？

我当时测了三个品牌：WIN、SIS、康比特。结果很“教科书”：
基本都是摄入后约 10 分钟开始上升，随后出现明显抬升。

为了让测试不至于变成“看个热闹”，我还给自己定了一个很朴素的评价标准：

• 升糖幅度（能不能把血糖拉起来）
• 维持时间（能不能撑住一段输出）

那段时间我一度觉得：这事儿挺科学的，能做成一套属于自己的“骑行能量胶测评方法”。

然后我被琐事打断了。测试停了，CGM 也就没再折腾。

半年后重启：我以为是继续更新数据，结果直接翻车

最近我又想起这件事：市面上还有很多胶没测，我决定把这个坑补上。

于是周六早上，我按之前的方式测了一个新品牌：Gio。

结果让我当场愣住：

• 几乎没有升糖反应
• 我等了将近 40 分钟 才看到一点点波动
• 血糖大概从 4.7 → 5.5 mmol/L
• 按我半年前的标准：不达标

但这事儿离谱就在于：能量胶这么甜，怎么可能“没效果”？
我不信邪，周六下午又测了一次——还是一样。

这时候我的怀疑方向开始从“胶不行”变成“我是不是出问题了”。更要命的是，周六我状态确实不太好，下午整个人有点迷糊，越想越像身体不对劲。

复测老朋友 WIN：我状态很好，但血糖依旧毫无波澜

周日早上醒来，我状态很好，精神也清爽。我决定做一个最直接的排查：

用半年前测过、当时表现“很正常”的 WIN 再测一次。
看看是我身体变了，还是胶变了，还是方法变了。

结果：WIN 也不升了。

后面明显血糖提升是我已经停止骑行了

那种感觉很微妙：
不是“数据不好看”的失落，而是“我一直以为这个方法靠谱，现在它好像失效了”的错愕。

我当时的心理活动大概是：

• 如果 Gio 不升糖，可能是胶的问题
• 但 WIN 也不升，那就很难怪胶
• 我今天状态又很好，不像身体出毛病
• 那到底发生了什么？

把曲线丢给 ChatGPT：一个我之前没认真想过的可能

我把半年前和最近的曲线发给 ChatGPT 让它帮我分析。它给了一个核心判断，听起来反直觉但很合理：

不是你吸收变差了，而是你“用得更快了”。
糖进来了，但还没来得及在血液里堆高，就被肌肉直接拿去用掉了。

它解释的方向主要是这些（我用自己的话压缩一下）：

• 训练适应后，肌肉即时摄糖能力变强：同样一包胶，过去会“血糖冲高”，现在可能直接被消耗掉
• 运动状态下肌肉收缩也能吸糖（不完全靠胰岛素那条路），骑得越规律这条路越“顺手”
• CGM 测到的是“血液/组织液里剩多少”，不等于“你吃进去了多少”

一句话总结就是：

半年前是“摄入 > 消耗”，所以曲线抬头明显；
现在更像“摄入 ≈ 消耗”，所以曲线看起来风平浪静。

当时我看到这套解释，第一反应不是“懂了”，而是“那我怎么确认不是瞎猜？”

我做了一个关键对照：静坐吃胶，血糖立刻起飞

周一上班，我干脆做了个更粗暴但有效的对照实验：
不骑车、不运动、静坐状态下吃一根 Gio。

结果非常清晰：血糖在短时间内迅速上升。

这一下基本把几个疑点都排掉了：

• 胶没问题（至少碳水摄入是实打实的）
• 我的吸收没问题
• CGM 也没坏

那剩下的解释就更集中：运动状态改变了“血糖呈现方式”。不是没吃进去，而是“进来就被用掉”，所以你在曲线上看不到当年那种抬升。

我真正的收获：我那套“测评标准”，其实脆弱得很

这次翻车让我重新认识了一件事：人体的变量多到离谱。

我半年前以为自己设计了一个挺科学的测评框架：看升糖幅度、看维持时间，然后给能量胶打分。现在回头看，这个框架至少有一个致命前提：

你的身体状态得相对稳定，你得能控制足够多的变量。

但现实是：

• 同一个人，不同训练周期、不同疲劳程度、不同睡眠、不同压力
• 同一种胶，可能会呈现完全不同的血糖曲线
• 甚至同一个周末，上午和下午都能不一样

所以也就不难理解：为什么大厂很少做这种“用血糖曲线评测能量胶效果”的公开对比。不是他们不想，是因为这事儿太难控制变量，结论很容易被误读。

接下来我准备怎么继续（这个坑我还想挖）

这次之后，我不太想把“能量胶评测”继续做成那种“谁升糖猛谁赢”的榜单了。更有意思的方向可能是：

• 运动 vs 静息 同一支胶的差异（像这次一样）
• 不同强度区间（Z2、爬坡、间歇） 同样摄入的曲线变化
• 把“血糖是否抬头”从结论，降级为一个观察维度
• 更关注：骑行主观感受、功率输出、胃部舒适度与血糖的对应关系

我现在越来越觉得：CGM 更像一面镜子，它照出来的不只是“胶怎么样”，更多是“我现在的身体处在什么状态”。

结尾：我以为我在测胶，结果是在测自己

这次最让我佩服的不是某个品牌的胶，也不是某条漂亮曲线，而是人体这套系统的精密程度：

我以为“吃胶＝升血糖”，结果运动状态下它可能变成“吃胶＝直接被肌肉拿走用掉”。
我以为我的方法很科学，结果它只是在一个特定阶段刚好有效。

这大概就是我喜欢做这种长期小实验的原因：
骑行没有标准答案，但数据会逼你承认——你还远远没弄懂自己。

服务器购买

选择云服务商

常见的云服务商有：

• 阿里云（推荐）
• 腾讯云
• 华为云
• 百度云

服务器配置建议

小型个人小程序推荐配置：

• CPU：1 核或 2 核
• 内存：2GB
• 带宽：1-3Mbps
• 系统盘：40GB
• 操作系统：CentOS 7.x 或 Ubuntu 18.04+

费用参考：

• 新用户通常有优惠，年费在 100-500 元不等
• 建议先购买 1 年，测试稳定后再续费

购买注意事项

1. 选择离目标用户较近的地域节点，可以降低延迟
2. 新用户可关注各大云平台的首购优惠
3. 学生用户可申请学生优惠
4. 注意查看带宽费用，避免后期流量费用过高

域名购买

购买域名 1 元起_.xin 首年 0 元_域名优惠活动 - 阿里云权益中心

选择合适的域名

小程序用户看不到域名，所以选择便宜的即可。用生日组合纯数字.xyz 域名最便宜。

选购技巧：

• 选择一个最便宜的域名时，注册时选择 2 年看看后期续费费用
• 如果一年 18 元，两年 120 元，说明第二年费用恢复原价，太贵了不要买
• 推荐选择续费价格稳定的域名后缀

常见便宜域名后缀：

• .xyz：首年最便宜，但续费可能较贵
• .top：价格适中
• .site：价格适中
• .club：价格适中

创建信息模板

下单时创建一个新的信息模板，避免之前创建过的填的信息不完善。购买之后会直接提交到域名注册局审核，信息不完善容易审核不通过。

信息模板填写注意事项：

• 姓名必须与身份证一致
• 地址填写详细，精确到门牌号
• 电话号码保持畅通，可能会接到审核电话
• 邮箱填写常用邮箱

域名实名认证

等待几小时（一般在 6 小时内），域名注册局实名认证成功，即可进行下一步备案。

实名认证材料：

• 个人：身份证正反面照片
• 企业：营业执照、法人身份证

域名解析

登录域名服务商，找到域名解析，添加解析记录。比如我在阿里云买的，从这里进入：

找到解析设置：

添加解析记录，第四步的IP地址就是你购买服务器后，服务器提供商给你的公网IP地址：

保存后，等待几分钟，解析记录就会生效。

SSL证书购买与部署

微信小程序必须使用Https协议，所以需要购买SSL证书。阿里云有免费的证书可以测试使用，但是有效期是3个月，需要定期续费。

从以下路径找到免费证书申请入口，你也可以在阿里云顶部搜索框搜索SSL，也能找到。

点击创建证书后，如实填写信息提交即可，然后等待签发：

快的话二十分钟就能签发，会给你发邮件提醒，之后就可以部署了：

点击部署，阿里云轻量ESC不支持一键部署，只能手动部署：

根据你的服务器类型选择SSL证书下载，我是用的Nginx。

部署我求助了AI工具，需要配置Nginx，我确实不会，这里我也不太好描述，还是自行问AI工具吧。

ICP 备案

点击网站备案_ICP 备案_备案迁移_App 备案_小程序备案_备案 - 阿里云开始备案。

准备材料

需要准备身份证，根据提示填写个人信息即可。

所需材料清单：

• 身份证正反面照片（清晰、完整）
• 手持身份证照片
• 幕布照片（部分云服务商需要）
• 域名证书
• 服务器证明（购买凭证）

备案流程

1. 填写备案信息
   • 主体信息（个人或企业信息）
   • 网站信息（网站名称、域名等）
   • 接入信息（服务器信息）

域名备注十分重要，如果是商业用途就需要上传营业执照等信息，这个我没经验，请自行研究。如果是个人用途，需要注明个人使用。比如我的域名其实是为了小程序的后端使用的，我备注的内容是xxx小程序后端API使用。 这样写是无法通过审核的，默认是有商业用途。所以我改成了：个人工具后端。 如果你是用于部署个人博客，有些省份是不能备案的，这个请你最好提前在购买域名的厂商客服那咨询一下。 有一些关键字是不能出现的，比如新闻、出版、教育、医疗等需要前置审批的内容。如果你涉及这些也需要咨询一下厂商客服。

2. 上传资料

   • 按要求上传各类证件照片
   • 确保照片清晰可见

3. 真实性核验

   • 部分地区需要视频核验
   • 按照要求进行人脸识别

4. 提交审核

   • 云服务商初审（1-2 个工作日）
   • 管局审核（3-20 个工作日，各地不同）

重要提醒

不能和小程序备案同步进行！ ICP 备案同一个主体（人）只能进行一个备案，需要当前备案结束后才能进行下一个。

备案时长：

• 首次备案：通常需要 10-20 个工作日
• 不同省份审核时间不同
• 遇到节假日会延长

我两次备案都是在10天完成。如果你在阿里云购买的服务器也是在阿里云购买域名备案，在域名关联服务器时候选的是阿里云的，那么阿里云会送服务器时长。备案花了多少条就会送多少天。

备案网站命名规范：

• 个人网站不能包含企业、行业等字样
• 不能涉及新闻、出版、教育、医疗等需要前置审批的内容
• 建议使用通用名称，如"XX 个人博客"、“XX 个人工具”

公安联网备案

域名证书下载

分步完成网站与APP公安联网备案申请-备案-阿里云

小程序备案

访问微信小程序公众平台进行备案。

备案流程

1. 补充小程序信息

   • 小程序名称
   • 简介
   • 服务类目
   • 服务范围等

2. 先提交微信官方审核

   • 微信会审核小程序信息是否合规
   • 审核时间通常为 1-3 个工作日

3. 审核通过自动提交到工信部审核

   • 工信部审核通过后，小程序备案完成
   • 审核时间通常为 7-20 个工作日

4. 审核不通过的处理

   • 审核不通过会电话联系，告知需要修改的地方
   • 注意：电话会被小米手机标记为广告电话，请在提交审核这几天及时接听广告电话，避免错过！
   • 小程序平台会站内信告知需要修改的地方，但是不如电话里说的清楚
   • 电话中不明白的可以及时问，但是错过电话就打不回去了

个人小程序备案说明

重要提示： 普通小工具类小程序不需要公司也不需要营业执照，用身份证提交就行。

但是小程序备注需要注明：给自己使用。

示例：

• 比如我开发了一个 Strava 贴纸合成到照片的小程序
• 我的备注是：用于给自己将两张图片合成为一张图片

备注填写技巧：

• 明确说明是个人使用
• 功能描述简洁明了
• 避免涉及商业用途
• 避免涉及社交、支付等敏感功能

小程序备案常见问题

Q1: 个人小程序可以选择哪些类目？

• 工具类（如计算器、记事本）
• 生活服务类（非商业）
• 体育类
• 教育类（非学历教育）

Q2: 个人小程序有哪些限制？

• 不能涉及支付功能
• 不能涉及社交功能
• 不能涉及直播功能
• 不能发布商业广告

Q3: 小程序备案失败常见原因

• 备注未说明个人使用
• 功能超出个人类目范围
• 服务器未备案或备案信息不一致
• 小程序名称不符合规范

小程序认证

小程序认证分为个人认证和企业认证，两者权限有较大差异。

个人小程序（未认证）

限制：

• 无法使用微信支付
• 无法使用卡券功能
• 无法使用附近的小程序
• 部分接口受限
• 每日访问用户数有上限

优势：

• 免费
• 审核流程简单
• 适合个人学习和小工具开发

企业认证

认证费用： 300 元/年（微信官方收取）

所需材料：

• 营业执照
• 法人身份证
• 对公账户信息（或法人微信支付）
• 企业邮箱

认证流程：

1. 登录小程序后台，点击"微信认证"
2. 填写企业信息
3. 上传营业执照等资料
4. 选择认证方式：
   • 对公账户打款验证（0.01 元，需 1-3 个工作日）
   • 法人微信扫码验证（即时验证，推荐）
5. 等待审核（通常 1-3 个工作日）

企业认证的优势：

• 开通微信支付功能
• 提升用户信任度
• 解锁更多 API 接口
• 无访问用户数限制
• 可以使用附近的小程序功能
• 可以发布卡券

认证注意事项

1. 企业认证必须是已注册的企业，个体工商户也可以
2. 年审： 企业认证每年需要重新认证，费用 300 元
3. 认证后不可更改主体，请谨慎选择
4. 认证信息要真实，虚假信息会导致认证失败甚至封号

开发环境配置

下载微信开发者工具

访问微信开发者工具下载页面，根据操作系统下载对应版本。

支持平台：

• Windows 64 位
• macOS
• Linux

申请 AppID

1. 登录微信公众平台
2. 进入小程序后台
3. 在"开发" -> “开发管理” -> “开发设置"中查看 AppID
4. 复制 AppID 备用

创建第一个小程序项目

1. 打开微信开发者工具
2. 扫码登录
3. 选择"小程序项目”
4. 点击"+“创建项目
5. 填写项目信息：
   • 项目名称
   • 目录（选择一个空文件夹）
   • AppID（填写之前复制的 AppID）
   • 开发模式（选择"小程序”）
   • 后端服务（选择"不使用云服务"，如需要后期可更改）
6. 点击"新建"

服务器配置

配置服务器域名

小程序只能与配置过的服务器域名进行网络通信。

配置步骤：

1. 登录微信公众平台
2. 进入"开发" -> “开发管理” -> “开发设置” -> “服务器域名”
3. 点击"修改"
4. 分别配置：
   • request 合法域名（用于 wx.request）
   • socket 合法域名（用于 wx.connectSocket）
   • uploadFile 合法域名（用于 wx.uploadFile）
   • downloadFile 合法域名（用于 wx.downloadFile）

域名要求：

• 必须是 HTTPS 协议
• 域名必须备案
• 域名不能使用 IP 地址
• 域名不能带端口号
• 一个月内最多修改 5 次

SSL 证书申请

免费证书来源：

• Let’s Encrypt（推荐，免费，90 天有效期）
• 阿里云免费证书（1 年有效期）
• 腾讯云免费证书（1 年有效期）

证书申请步骤（以阿里云为例）：

1. 登录阿里云控制台
2. 搜索"SSL 证书"
3. 选择"免费证书"
4. 填写域名信息
5. 选择 DNS 验证或文件验证
6. 完成验证后下载证书
7. 在服务器上配置证书（Nginx/Apache）

Nginx 配置示例

server {
    listen 443 ssl;
    server_name yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    ssl_session_cache shared:SSL:1m;
    ssl_session_timeout 5m;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# HTTP自动跳转HTTPS
server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}

小程序发布流程

代码开发

1. 在微信开发者工具中进行开发
2. 使用模拟器和真机预览测试
3. 确保代码符合微信小程序规范

代码上传

1. 在开发者工具中点击"上传"
2. 填写版本号和项目备注
3. 上传成功后可以在小程序后台看到

用户隐私保护指引设置

必须要设置这一项，否则上线后小程序还是会有问题，但是这些问题在调试版本里都不会出现。

进入账号设置：

拉到底部找到用户隐私保护指引

填写完需要审核，耐心等待。

为了能弹出对话框让用户同意隐私获取，需要在app.json中加入这行代码：

"__usePrivacyCheck__": true

这样小程序会在使用到获取隐私的接口时自动弹出来。

如果你的小程序定制化程度高，你也可以选择在你想要的时候弹出来，那么你需要参考官方文档微信公众平台，自行修改。

提交审核

1. 登录微信公众平台
2. 进入"版本管理"
3. 选择刚上传的版本
4. 点击"提交审核"
5. 填写审核信息：
   • 配置功能页面（至少添加一个页面）
   • 填写测试账号（如有登录功能）
   • 补充说明
6. 提交等待审核

审核时长：

• 一般 1-7 个工作日
• 首次审核可能较慢
• 节假日会延长

审核不通过处理

常见驳回原因：

• 服务类目不符
• 涉及未开放的接口
• 功能描述与实际不符
• 页面存在违规内容
• 测试账号无法登录

处理方法：

• 查看驳回原因
• 根据原因修改代码或说明
• 重新提交审核

发布上线

审核通过后：

1. 在"版本管理"中找到已通过审核的版本
2. 点击"发布"
3. 确认发布
4. 等待几分钟，小程序即可被用户搜索和使用

开发注意事项

开发规范

1. 代码规范

   • 使用 ES6 语法
   • 保持代码简洁易读
   • 合理使用组件化开发
   • 添加必要的注释

2. 性能优化

   • 图片压缩，使用 webp 格式
   • 合理使用分包加载
   • 避免频繁的 setData 操作
   • 及时清理定时器和监听器

3. 用户体验

   • 添加 loading 提示
   • 处理网络异常情况
   • 优化首屏加载速度
   • 适配不同机型

常见问题

Q1: 开发时如何调试 HTTPS 请求？

• 开发者工具中可以勾选"不校验合法域名"
• 但上线前必须配置好合法域名

Q2: 如何处理跨域问题？

• 小程序不存在跨域问题
• 但需要在服务器域名白名单中

Q3: 小程序包大小限制？

• 主包不能超过 2MB
• 所有分包总大小不能超过 20MB（使用分包优化后可达到更大）

Q4: 如何快速预览真机效果？

• 点击"预览"生成二维码
• 微信扫码即可在手机上预览

总结

微信小程序开发涉及的流程比较多，需要耐心完成每一步。主要流程总结如下：

1. ✅ 购买服务器和域名（注意选择性价比高的）
2. ✅ ICP 备案（10-20 个工作日，不能与小程序备案同时进行）
3. ✅ 小程序备案（7-20 个工作日，个人备案注意备注"给自己使用"）
4. ✅ 小程序认证（企业认证 300 元/年，个人可不认证）
5. ✅ 配置开发环境（下载开发者工具，申请 AppID）
6. ✅ 配置服务器域名（申请 SSL 证书，配置 HTTPS）
7. ✅ 开发与测试（遵循开发规范，注意性能优化）
8. ✅ 提交审核与发布（耐心等待审核，及时处理驳回）

时间规划建议：

• 备案阶段：预留 1 个月时间
• 开发阶段：根据项目复杂度安排
• 审核发布：预留 1 周时间

预算建议（个人小程序）：

• 服务器：100-500 元/年
• 域名：10-100 元/年
• SSL 证书：免费
• 小程序注册：免费（个人）
• 小程序认证：可选（企业 300 元/年）

希望这篇文章能帮助到正在开发小程序的朋友们，祝大家开发顺利！如有问题欢迎交流讨论。

在使用阿里云轻量服务器时，经常会遇到一个令人头疼的问题：默认配置没有 Swap 交换空间。当运行内存占用较高的应用（如编译项目、运行 CI/CD 流程、部署应用等）时，服务器经常会因为内存不足而卡死或无响应。

我在每次执行 Deploy 部署操作时都会遇到这个问题，机器直接卡死，无法继续工作。通过配置 Swap 交换空间，成功缓解了这一问题，现在运行稳定多了。

什么是 Swap？

Swap（交换空间）是 Linux 系统中的一种虚拟内存技术。当物理内存（RAM）不足时，系统会将暂时不用的数据从内存转移到硬盘上的 Swap 空间，从而释放内存供其他程序使用。虽然 Swap 的读写速度比物理内存慢，但它可以有效防止系统因内存不足而崩溃。

配置步骤

1. 检查当前 Swap 状态

首先，我们需要确认系统当前是否已经配置了 Swap：

free -h
swapon --show

如果 Swap 行显示为 0，说明系统没有配置交换空间。

2. 创建 Swap 文件

根据服务器内存大小，建议创建与内存容量相等或稍大的 Swap 空间。以 2GB 内存的服务器为例，创建 2GB 的 Swap 文件：

# 方法一：使用 fallocate 快速创建（推荐）
sudo fallocate -l 2G /swapfile

# 方法二：如果 fallocate 命令不可用，使用 dd 命令
sudo dd if=/dev/zero of=/swapfile bs=1G count=2

说明：

• /swapfile 是 Swap 文件的路径，可以根据需要修改
• 2G 表示创建 2GB 大小的文件
• fallocate 命令速度更快，优先使用

3. 设置文件权限

为了安全，Swap 文件应该只允许 root 用户读写：

sudo chmod 600 /swapfile

4. 格式化为 Swap 格式

将创建的文件格式化为 Swap 交换空间：

sudo mkswap /swapfile

5. 启用 Swap

激活刚刚创建的 Swap 文件：

sudo swapon /swapfile

6. 验证 Swap 是否生效

再次查看内存和 Swap 状态：

free -h

输出示例：

              total        used        free      shared  buff/cache   available
Mem:           2.0G        1.2G        100M         10M        700M        600M
Swap:          2.0G          0B        2.0G

可以看到 Swap 一行已经显示 2.0G，说明配置成功。

7. 配置开机自动挂载

为了让 Swap 在系统重启后自动生效，需要将其写入 /etc/fstab 文件：

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

验证 /etc/fstab 配置是否正确：

cat /etc/fstab

优化建议

调整 Swappiness 参数（可选）

swappiness 参数控制系统使用 Swap 的积极程度，取值范围 0-100：

• 0：尽可能不使用 Swap，只在内存完全不足时使用
• 60（默认值）：平衡使用物理内存和 Swap
• 100：积极使用 Swap

对于内存较小的服务器，建议将 swappiness 设置为 10-30，避免过度使用 Swap 导致性能下降：

# 查看当前 swappiness 值
cat /proc/sys/vm/swappiness

# 临时修改（重启后失效）
sudo sysctl vm.swappiness=10

# 永久修改
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

注意事项

1. 硬盘空间占用：Swap 文件会占用硬盘空间，创建前请确保有足够的磁盘空间
2. 性能影响：虽然 Swap 可以缓解内存不足问题，但过度使用会导致系统变慢，因为硬盘读写速度远低于内存
3. 监控使用情况：建议定期监控 Swap 的使用情况，如果经常大量使用 Swap，说明需要升级服务器配置或优化应用

监控 Swap 使用情况

实时查看内存和 Swap 状态

# 查看内存使用情况
free -h

# 持续监控（每 2 秒刷新一次）
watch -n 2 free -h

查看哪些进程在使用 Swap

for file in /proc/*/status ; do awk '/VmSwap|Name/{printf $2 " " $3}END{ print ""}' $file; done | sort -k 2 -n -r | head -10

删除 Swap（如需移除）

如果以后需要删除 Swap 配置，可以执行以下步骤：

# 1. 关闭 Swap
sudo swapoff /swapfile

# 2. 从 /etc/fstab 中删除对应行
sudo sed -i '/\/swapfile/d' /etc/fstab

# 3. 删除 Swap 文件
sudo rm /swapfile

总结

配置 Swap 是解决小内存服务器运行大型应用的有效方案。虽然不能完全替代物理内存，但可以在一定程度上缓解内存不足导致的系统卡死问题。对于阿里云轻量服务器这类默认没有 Swap 的环境，强烈建议配置 Swap 以提高系统稳定性。

当然，如果应用长期大量使用 Swap，最根本的解决方案还是升级服务器配置或优化应用程序的内存使用。

应用场景

OneDrive API 适用于以下开发场景:

• 跨设备数据同步: 浏览器插件、桌面应用的配置和数据同步
• 文件备份与恢复: 自动备份用户数据到云端,支持一键恢复
• 协作与分享: 实现文件共享、多人协作编辑功能
• 离线访问: 支持离线读取数据,在线自动同步

前置准备

在开始之前,你需要准备:

• ✅ Microsoft 账号(个人账号或工作/学校账号均可)
• ✅ 开发环境(本文以浏览器插件为例)
• ✅ 基础的 JavaScript/API 调用知识

💡 提示: OneDrive API 提供了免费的开发者配额,个人应用完全够用。

第一步: 注册 Azure 应用

1.1 访问 Azure Portal

1. 打开浏览器,访问 Azure Portal
2. 使用你的 Microsoft 账号登录
   • 个人账号(如 Outlook、Hotmail 邮箱)
   • 工作或学校账号(如公司/学校提供的 Office 365 账号)
3. 如果没有 Azure 账号,可以免费注册

📌 注意: 即使没有 Azure 订阅,也可以注册应用。免费账号足够用于开发测试。

1.2 进入应用注册页面

1. 在 Azure Portal 首页的搜索栏中输入 “Azure Active Directory” 或 “Microsoft Entra ID”
2. 点击搜索结果中的 Azure Active Directory 服务
3. 在左侧菜单中找到 “应用注册” (App registrations)
4. 点击顶部的 "+ 新注册" (New registration) 按钮

1.3 填写应用基本信息

在应用注册页面,需要填写以下关键信息:

应用名称

• 字段: 名称 (Name)
• 示例: QuickFillForm Extension 或 我的数据同步应用
• 说明: 这是应用的显示名称,用户授权时会看到此名称

支持的账户类型

选择应用的用户范围,推荐选择:

• ✅ 任何组织目录(任何 Azure AD 目录 - 多租户)中的帐户和个人 Microsoft 帐户(例如,Skype、Xbox)
• 英文选项: Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)

为什么选择这个选项?

• 支持个人 Microsoft 账号(最广泛的用户群)
• 支持企业和学校账号
• 不限制组织,任何人都可以使用你的应用

其他选项说明:

• 仅此组织目录: 仅限你的组织内部使用
• 任何组织目录: 仅限企业/学校账号,不支持个人账号
• 仅个人 Microsoft 账户: 仅支持个人账号

重定向 URI (Redirect URI)

这是 OAuth 认证完成后的回调地址,不同应用类型配置不同:

浏览器插件 (Chrome/Edge):

• 平台类型: Web
• URI 格式: https://<YOUR_EXTENSION_ID>.chromiumapp.org/onedrive
• 临时示例: https://abcdefghijklmnopqrstuvwxyz123456.chromiumapp.org/onedrive

Web 应用:

• 平台类型: Web
• URI 格式: https://yourdomain.com/callback
• 本地开发: http://localhost:3000/callback

桌面应用:

• 平台类型: 公共客户端/本机
• URI 格式: https://login.microsoftonline.com/common/oauth2/nativeclient

⚠️ 重要: 浏览器插件的 Extension ID 需要在插件安装后才能获取,稍后我们会更新这个配置。可以先填写一个临时值,或者留空后面再添加。

1.4 完成注册

确认信息无误后,点击页面底部的 “注册” (Register) 按钮。

注册成功后,会自动跳转到应用的 概述 (Overview) 页面,这里显示了应用的基本信息和重要 ID。

第二步: 配置 API 权限

注册完应用后,需要为应用添加访问 OneDrive 的权限。

2.1 进入 API 权限页面

1. 在应用详情页面的左侧菜单中,点击 “API 权限” (API permissions)
2. 你会看到默认已经添加了 User.Read 权限(这是用于读取用户基本信息的权限)

2.2 添加 Microsoft Graph 权限

1. 点击页面中的 "+ 添加权限" (Add a permission) 按钮
2. 在右侧弹出的面板中,点击 “Microsoft Graph”
3. 选择 “委托的权限” (Delegated permissions)

💡 权限类型说明:

• 委托的权限 (Delegated permissions): 应用代表已登录用户访问数据,需要用户授权
• 应用程序权限 (Application permissions): 应用以自己的身份访问数据,无需用户登录,需要管理员同意

2.3 选择所需权限

在搜索框中搜索并勾选以下权限:

Files.ReadWrite.AppFolder (推荐)

• 权限名称: Files.ReadWrite.AppFolder
• 权限级别: 委托的权限
• 作用: 允许应用读写应用专用文件夹中的文件
• 优势: 最安全的权限,应用只能访问自己创建的 Apps/<AppName> 文件夹
• 适用场景: 大多数应用数据同步场景

示例存储路径:

OneDrive/
└── Apps/
    └── QuickFillForm/
        ├── quickfillform-data.json
        └── backup/

offline_access (必需)

• 权限名称: offline_access
• 权限级别: 委托的权限
• 作用: 允许应用在用户离线时访问数据
• 用途: 获取刷新令牌(refresh token),在访问令牌过期后自动续期

Files.ReadWrite.All (可选,不推荐)

• 权限名称: Files.ReadWrite.All
• 权限级别: 委托的权限
• 作用: 允许应用读写用户的所有文件
• 风险: 权限范围过大,可能引起用户担忧
• 适用场景: 需要访问用户整个 OneDrive 的应用(如文件管理器)

2.4 确认添加权限

1. 勾选好权限后,点击底部的 “添加权限” (Add permissions) 按钮
2. 返回 API 权限页面,确认列表中显示以下权限:
   • ✅ User.Read (默认)
   • ✅ Files.ReadWrite.AppFolder
   • ✅ offline_access

2.5 授予管理员同意 (可选)

• 如果你是组织管理员,可以点击 “为 [组织名称] 授予管理员同意” 按钮
• 对于个人账号或公共应用,此步骤可以跳过
• 用户首次使用时会看到授权页面,点击"接受"即可

第三步: 获取应用凭据

3.1 复制 Client ID (应用程序 ID)

1. 在应用详情页面的 “概述” (Overview) 选项卡中
2. 找到 “应用程序(客户端) ID” (Application (client) ID)
3. 这是一个 GUID 格式的字符串,类似:

   12345678-1234-1234-1234-123456789abc
   

4. 点击旁边的复制图标,将 Client ID 保存到安全的地方

🔒 安全提示: Client ID 是公开信息,可以在前端代码中使用。但不要将它与 Client Secret 混淆。

3.2 是否需要 Client Secret?

对于不同类型的应用,Client Secret 的需求不同:

如果需要 Client Secret,创建方法如下:

1. 在左侧菜单中点击 “证书和密码” (Certificates & secrets)
2. 点击 "+ 新客户端密码" (New client secret)
3. 输入描述(如 “生产环境密钥”),选择过期时间
4. 点击 “添加” (Add)
5. 立即复制密钥值,此密钥只显示一次

⚠️ 警告: Client Secret 是敏感信息,必须妥善保管,不能提交到代码仓库。

3.3 配置身份验证设置

1. 在左侧菜单点击 “身份验证” (Authentication)
2. 确认 重定向 URI 已正确添加
3. 向下滚动到 “隐式授权和混合流” (Implicit grant and hybrid flows) 部分

对于浏览器插件或 SPA,需要启用:

• ✅ 勾选 “访问令牌” (Access tokens)
• ✅ 勾选 “ID 令牌” (ID tokens)

对于使用授权码流程的应用,可以不勾选上述选项

4. 点击页面底部的 “保存” (Save) 按钮

第四步: 配置应用代码

以浏览器插件为例,说明如何在代码中配置 OneDrive API。

4.1 获取浏览器插件的 Extension ID

如果你正在开发浏览器插件:

1. 打开 Chrome 或 Edge 浏览器
2. 访问 chrome://extensions/ (Chrome) 或 edge://extensions/ (Edge)
3. 开启右上角的 “开发者模式” (Developer mode)
4. 点击 “加载已解压的扩展程序” (Load unpacked)
5. 选择你的插件项目文件夹
6. 安装成功后,在插件卡片上找到 “ID” 字段,复制扩展 ID
   • 类似: abcdefghijklmnopqrstuvwxyz123456

4.2 更新 Azure 重定向 URI

1. 返回 Azure Portal 的应用注册页面
2. 进入 “身份验证” (Authentication)
3. 更新或添加重定向 URI:

   https://abcdefghijklmnopqrstuvwxyz123456.chromiumapp.org/onedrive
   

   • 将 abcdefghijklmnopqrstuvwxyz123456 替换为实际的扩展 ID
4. 点击 “保存” (Save)

4.3 在代码中配置 Client ID

以 QuickFillForm 插件为例,在 onedrive-sync.js 文件中配置:

class OneDriveSync {
    constructor() {
        // 替换为你的 Azure 应用程序 ID (Client ID)
        this.clientId = '12345678-1234-1234-1234-123456789abc';
        
        // 获取当前插件的 ID
        this.redirectUri = `https://${chrome.runtime.id}.chromiumapp.org/onedrive`;
        
        // Microsoft Graph API 端点
        this.graphEndpoint = 'https://graph.microsoft.com/v1.0';
        
        // 应用专用文件夹路径
        this.appFolderPath = '/me/drive/special/approot';
        
        // 请求的权限范围
        this.scopes = [
            'Files.ReadWrite.AppFolder',
            'offline_access'
        ];
    }
    
    // 获取访问令牌
    async getAccessToken() {
        return new Promise((resolve, reject) => {
            chrome.identity.launchWebAuthFlow({
                url: this.getAuthUrl(),
                interactive: true
            }, (redirectUrl) => {
                if (chrome.runtime.lastError) {
                    reject(chrome.runtime.lastError);
                    return;
                }
                
                // 从回调 URL 中提取 access_token
                const url = new URL(redirectUrl);
                const token = url.hash.match(/access_token=([^&]*)/)?.[1];
                
                if (token) {
                    resolve(token);
                } else {
                    reject(new Error('无法获取访问令牌'));
                }
            });
        });
    }
    
    // 构建授权 URL
    getAuthUrl() {
        const params = new URLSearchParams({
            client_id: this.clientId,
            response_type: 'token',
            redirect_uri: this.redirectUri,
            scope: this.scopes.join(' '),
            response_mode: 'fragment'
        });
        
        return `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?${params}`;
    }
    
    // 上传文件到 OneDrive
    async uploadFile(fileName, content) {
        const token = await this.getAccessToken();
        
        const response = await fetch(
            `${this.graphEndpoint}${this.appFolderPath}:/${fileName}:/content`,
            {
                method: 'PUT',
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(content)
            }
        );
        
        if (!response.ok) {
            throw new Error(`上传失败: ${response.statusText}`);
        }
        
        return await response.json();
    }
    
    // 从 OneDrive 下载文件
    async downloadFile(fileName) {
        const token = await this.getAccessToken();
        
        const response = await fetch(
            `${this.graphEndpoint}${this.appFolderPath}:/${fileName}:/content`,
            {
                headers: {
                    'Authorization': `Bearer ${token}`
                }
            }
        );
        
        if (!response.ok) {
            throw new Error(`下载失败: ${response.statusText}`);
        }
        
        return await response.json();
    }
}

// 使用示例
const onedriveSync = new OneDriveSync();

// 上传数据
onedriveSync.uploadFile('data.json', { key: 'value' })
    .then(() => console.log('上传成功'))
    .catch(err => console.error('上传失败:', err));

// 下载数据
onedriveSync.downloadFile('data.json')
    .then(data => console.log('下载的数据:', data))
    .catch(err => console.error('下载失败:', err));

4.4 Web 应用配置示例

对于传统 Web 应用(有后端),使用授权码流程更安全:

// 前端代码
function loginWithOneDrive() {
    const clientId = 'YOUR_CLIENT_ID';
    const redirectUri = 'https://yourdomain.com/callback';
    const scopes = 'Files.ReadWrite.AppFolder offline_access';
    
    const authUrl = `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?` +
        `client_id=${clientId}` +
        `&response_type=code` +
        `&redirect_uri=${encodeURIComponent(redirectUri)}` +
        `&scope=${encodeURIComponent(scopes)}`;
    
    window.location.href = authUrl;
}

// 后端代码 (Node.js Express 示例)
app.get('/callback', async (req, res) => {
    const code = req.query.code;
    
    // 用授权码换取访问令牌
    const tokenResponse = await fetch('https://login.microsoftonline.com/common/oauth2/v2.0/token', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: new URLSearchParams({
            client_id: process.env.CLIENT_ID,
            client_secret: process.env.CLIENT_SECRET,
            code: code,
            redirect_uri: 'https://yourdomain.com/callback',
            grant_type: 'authorization_code'
        })
    });
    
    const tokenData = await tokenResponse.json();
    
    // 保存 access_token 和 refresh_token
    req.session.accessToken = tokenData.access_token;
    req.session.refreshToken = tokenData.refresh_token;
    
    res.redirect('/dashboard');
});

4.5 配置 manifest.json (浏览器插件)

在插件的 manifest.json 中添加必要的权限:

{
    "manifest_version": 3,
    "name": "QuickFillForm",
    "version": "1.0.0",
    "permissions": [
        "identity",
        "storage"
    ],
    "host_permissions": [
        "https://login.microsoftonline.com/*",
        "https://graph.microsoft.com/*"
    ],
    "oauth2": {
        "client_id": "12345678-1234-1234-1234-123456789abc.chromiumapp.org",
        "scopes": [
            "Files.ReadWrite.AppFolder",
            "offline_access"
        ]
    }
}

第五步: 测试同步功能

5.1 测试用户认证

1. 在应用中触发 OneDrive 登录流程
2. 浏览器会打开 Microsoft 登录页面
3. 输入 Microsoft 账号和密码登录
4. 首次使用会看到权限请求页面:
   • 显示应用名称
   • 列出请求的权限
   • 显示应用发布者信息
5. 点击 “接受” (Accept) 按钮授权

5.2 测试文件上传

浏览器插件示例:

// 测试上传功能
async function testUpload() {
    const testData = {
        name: '张三',
        email: 'zhangsan@example.com',
        phone: '13800138000'
    };
    
    try {
        const result = await onedriveSync.uploadFile('test-data.json', testData);
        console.log('✅ 上传成功:', result);
    } catch (error) {
        console.error('❌ 上传失败:', error);
    }
}

testUpload();

5.3 测试文件下载

// 测试下载功能
async function testDownload() {
    try {
        const data = await onedriveSync.downloadFile('test-data.json');
        console.log('✅ 下载成功:', data);
    } catch (error) {
        console.error('❌ 下载失败:', error);
    }
}

testDownload();

5.4 验证文件存储位置

1. 登录 OneDrive 网页版
2. 在左侧菜单中找到 “应用” (Apps) 文件夹
3. 进入你的应用文件夹,例如 Apps/QuickFillForm/
4. 确认文件已成功上传

5.5 测试跨设备同步

1. 在设备 A 上传数据
2. 在设备 B 上登录同一 Microsoft 账号
3. 下载数据,验证是否与设备 A 一致
4. 修改数据后再次上传
5. 在设备 A 上下载,验证是否更新

常见问题与解决方案

Q1: 无法获取访问令牌

错误信息:

AADSTS50011: The redirect URI specified in the request does not match

原因分析:

• Client ID 配置错误
• 重定向 URI 不匹配
• Extension ID 更改后未更新 Azure 配置

解决方案:

1. 检查代码中的 clientId 是否正确复制

   // 错误: 多余的空格或特殊字符
   this.clientId = '12345678-1234-1234-1234-123456789abc ';
   
   // 正确
   this.clientId = '12345678-1234-1234-1234-123456789abc';
   

2. 确认 Azure 应用注册中的重定向 URI 与代码完全一致

   • Azure 配置: https://abcdefg123456.chromiumapp.org/onedrive
   • 代码配置: https://abcdefg123456.chromiumapp.org/onedrive
   • 注意区分大小写和尾部斜杠

3. 保存配置后等待 2-5 分钟让配置生效

Q2: 权限被拒绝,无法读写文件

错误信息:

403 Forbidden: Access denied

原因分析:

• 权限未正确添加
• 用户未授权
• 使用了错误的 API 端点

解决方案:

1. 在 Azure Portal 检查是否已添加 Files.ReadWrite.AppFolder 权限
2. 清除用户授权,重新登录并同意权限

   // 清除缓存的令牌
   chrome.identity.clearAllCachedAuthTokens(() => {
       console.log('已清除缓存,请重新登录');
   });
   

3. 确认使用正确的 API 路径:

   // 正确: 使用应用专用文件夹
   const path = '/me/drive/special/approot:/data.json:/content';
   
   // 错误: 使用根目录 (需要 Files.ReadWrite.All 权限)
   const path = '/me/drive/root:/data.json:/content';
   

Q3: 访问令牌过期

错误信息:

401 Unauthorized: The access token has expired

原因分析:

• Access Token 默认有效期 1 小时
• 未实现 Refresh Token 自动刷新机制

解决方案:

实现令牌刷新逻辑:

class OneDriveSync {
    constructor() {
        this.accessToken = null;
        this.refreshToken = null;
        this.tokenExpiry = null;
    }
    
    // 获取有效的访问令牌
    async getValidAccessToken() {
        // 如果令牌未过期,直接返回
        if (this.accessToken && this.tokenExpiry > Date.now()) {
            return this.accessToken;
        }
        
        // 如果有刷新令牌,尝试刷新
        if (this.refreshToken) {
            return await this.refreshAccessToken();
        }
        
        // 否则重新登录
        return await this.getAccessToken();
    }
    
    // 刷新访问令牌
    async refreshAccessToken() {
        const response = await fetch('https://login.microsoftonline.com/common/oauth2/v2.0/token', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: new URLSearchParams({
                client_id: this.clientId,
                refresh_token: this.refreshToken,
                grant_type: 'refresh_token'
            })
        });
        
        const data = await response.json();
        
        this.accessToken = data.access_token;
        this.refreshToken = data.refresh_token;
        this.tokenExpiry = Date.now() + (data.expires_in * 1000);
        
        // 保存到本地存储
        chrome.storage.local.set({
            onedrive_access_token: this.accessToken,
            onedrive_refresh_token: this.refreshToken,
            onedrive_token_expiry: this.tokenExpiry
        });
        
        return this.accessToken;
    }
}

Q4: 找不到扩展 ID

解决方案:

1. 访问浏览器的扩展管理页面:
   • Chrome: chrome://extensions/
   • Edge: edge://extensions/
2. 确保已开启"开发者模式"
3. Extension ID 显示在扩展卡片上,格式类似:

   ID: abcdefghijklmnopqrstuvwxyz123456
   

4. 如果是已发布的扩展,可以在 Chrome Web Store 的 URL 中找到:

   https://chrome.google.com/webstore/detail/extension-name/abcdefghijklmnopqrstuvwxyz123456
   

Q5: 文件上传成功但在 OneDrive 中找不到

原因分析:

• 使用了应用专用文件夹,路径在 Apps/<AppName>/ 下
• OneDrive 网页版界面可能有延迟
• 文件名或路径错误

解决方案:

1. 在 OneDrive 网页版中,导航到:

   OneDrive → 应用 (Apps) → QuickFillForm
   

2. 等待 1-2 分钟,刷新页面
3. 使用 API 查询文件是否存在:

   // 列出应用文件夹中的所有文件
   async function listFiles() {
       const token = await onedriveSync.getValidAccessToken();
   
       const response = await fetch(
           'https://graph.microsoft.com/v1.0/me/drive/special/approot/children',
           {
               headers: { 'Authorization': `Bearer ${token}` }
           }
       );
   
       const data = await response.json();
       console.log('文件列表:', data.value);
   }
   

Q6: 跨域请求被阻止 (CORS)

错误信息:

Access to fetch at 'https://graph.microsoft.com/...' has been blocked by CORS policy

原因分析:

• 在普通网页中直接请求 Graph API
• 未在 manifest.json 中配置 host_permissions

解决方案:

方案一: 使用后端代理 (推荐)

// 前端调用后端 API
fetch('/api/onedrive/upload', {
    method: 'POST',
    body: JSON.stringify(data)
});

// 后端转发到 Microsoft Graph
app.post('/api/onedrive/upload', async (req, res) => {
    const response = await fetch('https://graph.microsoft.com/v1.0/...', {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    });
    // ...
});

方案二: 浏览器插件配置

{
    "host_permissions": [
        "https://login.microsoftonline.com/*",
        "https://graph.microsoft.com/*"
    ]
}

Q7: 授权页面显示"需要管理员审批"

错误信息:

AADSTS65001: The user or administrator has not consented to use the application

原因分析:

• 组织策略要求管理员批准应用
• 请求的权限需要管理员同意

解决方案:

1. 如果你是管理员,在 Azure Portal 中授予管理员同意
2. 如果不是管理员,联系 IT 部门批准应用
3. 使用个人 Microsoft 账号测试(个人账号无需管理员同意)
4. 减少权限请求,只使用委托权限而不是应用权限

安全最佳实践

1. 保护 Client Secret

// ❌ 错误: 在前端代码中硬编码密钥
const clientSecret = 'your-secret-key-123456';

// ✅ 正确: 在后端使用环境变量
const clientSecret = process.env.AZURE_CLIENT_SECRET;

2. 使用最小权限原则

// ❌ 错误: 请求过多权限
const scopes = [
    'Files.ReadWrite.All',
    'Mail.Read',
    'Contacts.ReadWrite'
];

// ✅ 正确: 只请求必需的权限
const scopes = [
    'Files.ReadWrite.AppFolder',
    'offline_access'
];

3. 安全存储令牌

// ✅ 浏览器插件: 使用 chrome.storage.local
chrome.storage.local.set({
    onedrive_token: encryptedToken  // 最好加密存储
});

// ✅ Web 应用: 使用 HttpOnly Cookie
res.cookie('access_token', token, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict'
});

4. 定期检查应用活动

1. 登录 Azure Portal
2. 进入应用注册 → 你的应用
3. 查看 “概述” 中的使用情况统计
4. 检查异常登录和 API 调用

5. 处理敏感数据

// 上传前加密敏感数据
async function uploadSecureData(data) {
    const encrypted = await encryptData(data);
    await onedriveSync.uploadFile('secure-data.enc', encrypted);
}

// 下载后解密
async function downloadSecureData() {
    const encrypted = await onedriveSync.downloadFile('secure-data.enc');
    return await decryptData(encrypted);
}

进阶技巧

1. 实现文件版本管理

OneDrive 自动保留文件版本历史,可以通过 API 访问:

async function getFileVersions(fileName) {
    const token = await onedriveSync.getValidAccessToken();
    
    const response = await fetch(
        `https://graph.microsoft.com/v1.0/me/drive/special/approot:/${fileName}:/versions`,
        {
            headers: { 'Authorization': `Bearer ${token}` }
        }
    );
    
    const data = await response.json();
    return data.value;  // 返回版本列表
}

2. 实现增量同步

通过 Delta API 获取文件变化:

async function syncChanges(deltaLink) {
    const token = await onedriveSync.getValidAccessToken();
    
    const url = deltaLink || 
        'https://graph.microsoft.com/v1.0/me/drive/special/approot/delta';
    
    const response = await fetch(url, {
        headers: { 'Authorization': `Bearer ${token}` }
    });
    
    const data = await response.json();
    
    // 处理变化的文件
    for (const item of data.value) {
        if (item.deleted) {
            console.log('文件已删除:', item.name);
        } else {
            console.log('文件已更新:', item.name);
        }
    }
    
    // 保存 deltaLink 供下次使用
    return data['@odata.deltaLink'];
}

3. 实现冲突解决

async function smartSync(fileName, localData) {
    try {
        // 下载远程文件
        const remoteData = await onedriveSync.downloadFile(fileName);
        
        // 比较时间戳
        if (remoteData.lastModified > localData.lastModified) {
            // 远程更新,下载覆盖本地
            return { action: 'download', data: remoteData };
        } else if (localData.lastModified > remoteData.lastModified) {
            // 本地更新,上传覆盖远程
            await onedriveSync.uploadFile(fileName, localData);
            return { action: 'upload', data: localData };
        } else {
            // 智能合并
            const merged = mergeData(localData, remoteData);
            await onedriveSync.uploadFile(fileName, merged);
            return { action: 'merge', data: merged };
        }
    } catch (error) {
        // 文件不存在,直接上传
        if (error.status === 404) {
            await onedriveSync.uploadFile(fileName, localData);
            return { action: 'create', data: localData };
        }
        throw error;
    }
}

4. 批量操作

使用批处理 API 提高性能:

async function batchUpload(files) {
    const token = await onedriveSync.getValidAccessToken();
    
    const requests = files.map((file, index) => ({
        id: index.toString(),
        method: 'PUT',
        url: `/me/drive/special/approot:/${file.name}:/content`,
        headers: {
            'Content-Type': 'application/json'
        },
        body: file.content
    }));
    
    const response = await fetch('https://graph.microsoft.com/v1.0/$batch', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ requests })
    });
    
    return await response.json();
}

相关资源

官方文档

• 📘 Microsoft Graph API 文档
• 📘 OneDrive API 参考
• 📘 Azure AD 应用注册指南
• 📘 OAuth 2.0 授权流程

开发工具

• 🛠️ Graph Explorer - 在线测试 API
• 🛠️ Microsoft Graph SDK - 各语言 SDK
• 🛠️ Postman Collection - API 调试

示例项目

• 💻 OneDrive JavaScript SDK
• 💻 浏览器插件 OAuth 示例

社区资源

• 💬 Microsoft Graph 开发者论坛
• 💬 Stack Overflow - microsoft-graph

应用场景

SFTP 插件适用于以下场景：

• 本地开发，远程调试：在本地编写代码，保存后自动同步到远程服务器，无需手动上传
• 快速部署：本地测试通过后，一键同步到生产环境服务器
• 多服务器管理：同时管理多个远程服务器，快速切换上传目标
• 团队协作：统一开发环境，确保代码在服务器端运行一致

安装插件

打开 VSCode，按下快捷键 Ctrl + Shift + X 打开扩展商店，搜索 sftp，找到名为 SFTP 的插件（作者：Natizyskunk），这是安装量最高、最受欢迎的 SFTP 插件。点击安装即可。

安装完成后，VSCode 会在侧边栏显示 SFTP 图标，表示插件已成功安装。

配置插件

生成配置文件

插件安装完成后，我们需要为当前项目创建配置文件。有两种方式：

方式一：使用命令面板

1. 按下快捷键 Ctrl + Shift + P 打开命令面板
2. 输入 SFTP: Config 并回车
3. VSCode 会在当前工作区的 .vscode 文件夹下自动生成 sftp.json 配置文件

方式二：右键菜单

1. 在 VSCode 资源管理器中，右键点击项目文件夹
2. 选择 SFTP: Config
3. 同样会生成 sftp.json 配置文件

基础配置示例

打开生成的 sftp.json 文件，你会看到一个默认的配置模板。下面是一个基础配置示例：

{
    "name": "我的服务器",
    "host": "192.168.1.100",
    "protocol": "sftp",
    "port": 22,
    "username": "root",
    "password": "your_password",
    "remotePath": "/var/www/project",
    "uploadOnSave": true,
    "useTempFile": false,
    "openSsh": false
}

完整配置示例

下面是一个包含更多选项的完整配置示例：

{
    "name": "生产环境服务器",
    "host": "192.168.1.100",
    "protocol": "sftp",
    "port": 22,
    "username": "deployer",
    "password": "your_password",
    "remotePath": "/home/deployer/project",
    "context": "./",
    "uploadOnSave": true,
    "useTempFile": false,
    "openSsh": false,
    "downloadOnOpen": false,
    "ignore": [
        ".vscode",
        ".git",
        ".DS_Store",
        "node_modules",
        "*.log",
        "*.tmp"
    ],
    "watcher": {
        "files": "**/*",
        "autoUpload": true,
        "autoDelete": false
    },
    "syncOption": {
        "delete": false,
        "skipCreate": false,
        "ignoreExisting": false,
        "update": true
    },
    "sshConfigPath": null,
    "concurrency": 4
}

配置参数详解

连接配置参数

认证方式参数

SFTP 插件支持三种认证方式：

1. 密码认证（最简单）

{
    "username": "root",
    "password": "your_password"
}

2. 密钥认证（推荐）

{
    "username": "root",
    "privateKeyPath": "C:\\Users\\YourName\\.ssh\\id_rsa",
    "passphrase": "密钥密码（如果有的话）"
}

密钥文件路径说明：

• Windows: C:\\Users\\YourName\\.ssh\\id_rsa 或 ~/.ssh/id_rsa
• Linux/Mac: ~/.ssh/id_rsa
• 支持 OpenSSH 格式和 PPK 格式的密钥

3. SSH Config 配置（高级）

如果你已经配置了 SSH config 文件，可以直接引用：

{
    "sshConfigPath": "~/.ssh/config",
    "host": "myserver"
}

对应的 SSH config 文件内容：

Host myserver
    HostName 192.168.1.100
    User deployer
    Port 22
    IdentityFile ~/.ssh/id_rsa

路径配置参数

路径配置说明：

假设本地项目结构如下：

project/
├── src/
│   ├── index.js
│   └── utils.js
├── tests/
└── .vscode/
    └── sftp.json

• 如果 context 为 "./" 且 remotePath 为 "/var/www/project"，则 src/index.js 会上传到 /var/www/project/src/index.js
• 如果 context 为 "./src" 且 remotePath 为 "/var/www/project"，则 src/index.js 会上传到 /var/www/project/index.js

自动同步参数

最佳实践建议：

• 开发环境：设置 uploadOnSave: true，方便快速同步
• 生产环境：设置 uploadOnSave: false，避免误操作

忽略文件配置

ignore 参数用于指定哪些文件或文件夹不需要同步，支持 glob 模式：

{
    "ignore": [
        "**/.vscode/**",
        "**/.git/**",
        "**/.DS_Store",
        "**/node_modules/**",
        "**/*.log",
        "**/*.tmp",
        "**/dist/**",
        "**/coverage/**"
    ]
}

常用忽略模式：

• **/.git/**：忽略 Git 版本控制文件
• **/node_modules/**：忽略 Node.js 依赖包
• **/*.log：忽略所有日志文件
• **/dist/**：忽略构建输出目录

监听器配置（Watcher）

监听器可以监控文件变化并自动执行同步操作：

{
    "watcher": {
        "files": "**/*",
        "autoUpload": true,
        "autoDelete": false
    }
}

注意事项：

• autoDelete: true 可能导致误删除，请谨慎使用
• 监听器会持续运行，可能影响性能，建议按需启用

同步选项（Sync Option）

syncOption 用于配置手动同步时的行为：

{
    "syncOption": {
        "delete": false,
        "skipCreate": false,
        "ignoreExisting": false,
        "update": true
    }
}

性能优化参数

{
    "concurrency": 8,
    "connectTimeout": 15000,
    "keepalive": 5000
}

性能优化建议：

• 网络环境好时，可以增加 concurrency 提高上传速度
• 网络不稳定时，增加 connectTimeout 避免连接超时
• 频繁操作时，减小 keepalive 保持连接活跃

插件使用

常用操作

安装并配置好插件后，可以通过以下方式使用：

1. 上传文件或文件夹

方式一：右键菜单

• 在资源管理器中右键点击文件或文件夹
• 选择 Upload 上传到服务器

方式二：命令面板

• 按 Ctrl + Shift + P 打开命令面板
• 输入 SFTP: Upload 并选择相应的命令

2. 下载文件或文件夹

• 右键点击文件或文件夹
• 选择 Download 从服务器下载

3. 同步操作

同步本地到远程：

• 命令面板输入 SFTP: Sync Local -> Remote
• 将本地所有文件同步到服务器

同步远程到本地：

• 命令面板输入 SFTP: Sync Remote -> Local
• 将服务器文件同步到本地

双向同步：

• 命令面板输入 SFTP: Sync Both Directions
• 根据文件修改时间自动判断同步方向

4. 对比文件差异

• 右键点击文件
• 选择 Diff with Remote
• VSCode 会显示本地文件和远程文件的差异

5. 列出远程文件

• 命令面板输入 SFTP: List
• 可以浏览远程服务器的文件目录

完整命令列表

按 Ctrl + Shift + P 打开命令面板，输入 SFTP 可以看到所有可用命令：

多服务器配置

在实际开发中，我们可能需要同时管理开发环境、测试环境和生产环境多个服务器。SFTP 插件支持在一个配置文件中配置多个服务器。

配置多个服务器

在 sftp.json 中使用数组格式配置多个服务器：

[
    {
        "name": "开发环境",
        "host": "192.168.1.101",
        "port": 22,
        "username": "developer",
        "password": "dev_password",
        "protocol": "sftp",
        "remotePath": "/home/developer/project",
        "uploadOnSave": true,
        "ignore": [
            ".vscode/**",
            ".git/**",
            "node_modules/**"
        ]
    },
    {
        "name": "测试环境",
        "host": "192.168.1.102",
        "port": 22,
        "username": "tester",
        "password": "test_password",
        "protocol": "sftp",
        "remotePath": "/var/www/test",
        "uploadOnSave": false,
        "ignore": [
            ".vscode/**",
            ".git/**",
            "node_modules/**"
        ]
    },
    {
        "name": "生产环境",
        "host": "192.168.1.103",
        "port": 22,
        "username": "deployer",
        "privateKeyPath": "~/.ssh/production_key",
        "protocol": "sftp",
        "remotePath": "/var/www/production",
        "uploadOnSave": false,
        "ignore": [
            ".vscode/**",
            ".git/**",
            "node_modules/**",
            "*.log"
        ]
    }
]

切换服务器

配置多个服务器后，每次执行上传、下载等操作时，VSCode 会弹出选择框，让你选择目标服务器。

也可以通过命令面板 SFTP: List All 查看所有配置的服务器。

最佳实践

1. 安全配置建议

不要将密码明文写入配置文件：

方案一：使用环境变量

{
    "username": "${env.SFTP_USER}",
    "password": "${env.SFTP_PASSWORD}"
}

方案二：使用密钥认证（推荐）

{
    "username": "deployer",
    "privateKeyPath": "~/.ssh/id_rsa"
}

将配置文件加入 .gitignore：

.vscode/sftp.json

如果需要团队共享配置，可以创建一个 sftp.json.example 模板文件，将敏感信息替换为占位符：

{
    "name": "示例配置",
    "host": "your_server_ip",
    "username": "your_username",
    "password": "your_password",
    "remotePath": "/path/to/project"
}

2. 工作流建议

开发阶段：

{
    "uploadOnSave": true,
    "downloadOnOpen": false,
    "watcher": {
        "autoUpload": true
    }
}

部署阶段：

{
    "uploadOnSave": false,
    "syncOption": {
        "update": true,
        "delete": false
    }
}

3. 团队协作建议

为团队创建统一的配置模板：

{
    "name": "团队开发服务器",
    "host": "${env.DEV_SERVER}",
    "username": "${env.DEV_USER}",
    "password": "${env.DEV_PASSWORD}",
    "remotePath": "/home/${env.DEV_USER}/project",
    "uploadOnSave": true,
    "ignore": [
        ".vscode/**",
        ".git/**",
        ".env",
        "node_modules/**",
        "*.log"
    ]
}

团队成员在本地创建 .env 文件配置自己的环境变量即可。

4. 性能优化建议

对于大型项目，建议优化以下配置：

{
    "concurrency": 8,
    "ignore": [
        "node_modules/**",
        "dist/**",
        "build/**",
        ".git/**",
        "**/*.log"
    ],
    "syncOption": {
        "update": true
    }
}

常见问题

1. 连接超时

**问题：**上传文件时提示连接超时。

解决方案：

• 检查服务器 IP 和端口是否正确
• 检查防火墙是否开放对应端口
• 增加 connectTimeout 参数：

  {
      "connectTimeout": 30000
  }
  

2. 权限不足

**问题：**上传文件提示 Permission denied。

解决方案：

• 确认登录用户对目标目录有写权限
• 在服务器上执行：chmod 755 /target/path
• 或切换到有权限的用户

3. 密钥认证失败

**问题：**使用密钥登录时提示认证失败。

解决方案：

• 确认密钥文件路径正确
• 确认密钥文件权限：chmod 600 ~/.ssh/id_rsa
• 如果密钥有密码，需要配置 passphrase
• Windows 用户注意路径格式：C:\\Users\\Name\\.ssh\\id_rsa

4. 文件同步冲突

**问题：**本地和远程文件都被修改，不知道以哪个为准。

解决方案：

• 使用 Diff with Remote 对比差异
• 手动合并代码后再上传
• 使用版本控制工具如 Git 管理代码

5. 上传速度慢

**问题：**上传大量文件时速度很慢。

解决方案：

• 增加并发数："concurrency": 10
• 完善 ignore 配置，避免上传不必要的文件
• 使用 Sync Local -> Remote 而不是 Upload Folder

参考资料

• SFTP 插件官方文档
• SSH 密钥认证配置
• SFTP 协议介绍

Meta Quest 3 是一款优秀的 VR 一体机，但在国内激活存在网络限制问题。本文将介绍如何使用 Netch 工具，通过 Windows 电脑配置网络代理，实现 Quest 3 在国内的顺利激活。

准备工作

在开始之前，你需要准备以下内容：

• Windows 电脑一台
• 一个路由器
• VPN 代理

获取代理服务

首先需要获取一个 VPN 代理服务。可以访问以下任意链接注册，必须支持 UDP 转发，连接 WiFi 时需要对设备进行时间校准，这个校准步骤就同时验证这个 WiFi 是否可以连网，但这个校准是基于 UDP 的，只开启梯子的系统代理只能走 TCP 又不支持 UDP，所以只能上网不能校准时间。绝大部分机场不支持 UDP，你可以咨询机场客服是否支持 UDP 转发，也可以参考这篇文档Quest 网络受限原因 | Meta Quest 中文指南，测试是否支持 UDP。

如果你没有代理，或者代理不支持 UDP，可以考虑使用以下代理，我已经测试过：

• 龙猫云
• 老猫云
• Web3加速器

选最便宜的买就行，买一个月，后续可能会用其他不支持 UDP 便宜的机场，所以不要买贵的。我之前用的机场就不支持 UDP，但是平时使用完全够用，只有在 Quest3 激活是用到过这一次 UDP。

日常使用可以考虑便宜大碗的Glados，目前至少稳定运行了10年了。

机场注册之后注意看一下是否支持导出订阅地址，有一些机场只能使用自己的客户端，那就无法使用 Netch。请一定要注意！！！因为文章可能维护不及时，我也不保证上面的机场是否还支持导出订阅地址。之前使用过万达云的机场，用了一天就因为无法导出订阅地址无法使用了。他家改成只能使用自己的客户端了。

Netch 配置步骤

下载 Netch

从Netch 开源主页下载最新版本。

重要提示：使用 Netch 时不能同时开启其他代理软件！如果之前有开启其他代理，请全部关闭后重启电脑。

安装 Netch

1. 解压下载的压缩包到任意磁盘根目录
2. 运行 Netch.exe 文件

安装 Npcap

前往官网下载 Npcap 并安装Npcap: Windows Packet Capture Library & Driver。

安装时选择：

• Support raw 802.11 traffic
• Install Npcap in WinPcap API-Compatible Mode

添加订阅

1. 点击上方的"订阅" → “管理订阅”
   1. 
2. 添加订阅链接
   1. 

更新服务器

1. 点击上方的"订阅" → “更新服务器”
   1. 
2. 如果更新失败，检查订阅链接是否正确，确保关闭所有其他代理软件

选择节点

1. 点击"服务器"，选择一个节点，优先选择美国节点
2. 如果是自己的代理服务，可以多尝试不同节点

选择模式

点击"模式"，选择 [pcap2socks]Tencent(10.6.0.1)Preset

配置 DNS

1. 点击"设置"
   1. 
2. 切换到"WinTUN"选项卡
3. 勾选"使用自定义 DNS"
4. 勾选"代理 DNS"
5. 将 DNS 改为 1.1.1.1
6. 点击右下角"保存"

启动 Netch

点击右下角的"启动"按钮，等待启动完成。

判断启动成功：

• “启动"按钮变成"停止”
• 下方出现绿色圆形标志

软件右侧出现以下终端窗口：

Quest 3 激活流程

1. 连接 WiFi

1. 启动 Quest 3
2. 在语言选择界面选择"简体中文"
3. 选择"在头戴设备中输入 WIFI 信息"
4. 选择你的路由器 WiFi，不要点击连接，需要后面配置高级选项

2. 配置静态 IP

1. 输入 WiFi 密码后，点击"高级选项"

2. 将 IP 设置从"DHCP"改为"静态"

3. 配置静态 IP 地址

   1. IP 地址：10.6.0.1
   2. 网关：10.6.0.2
   3. 网络前缀长度：24
   4. DNS1:8.8.8.8

4. 滚动到页面最下方，点击"连接"

正常情况下点击连接后，Netch 软件旁边的终端窗口会有响应，有一行输出提示某一个 IP 地址设备加入了链接。

3. 系统更新

连接成功后，Quest 3 会自动进入更新流程。按照我的经验，激活过程中经常断连，所以需要多尝试几次。不要开始更新就把机器扔一边，经常看看。

常见问题处理

提示"Wrong STUN Server"

进入设置，将 STUN 服务器改为以下任意一个：

• stun.voipstunt.com
• stun.xten.com
• stun.ekiga.net

没有绿点或显示 NOUDP/UnsupportedServer

可能的解决方案：

1. 刷新状态：点击 NOUDP 刷新几次，如果变成黄点或红点也可能能用
2. 兼容性问题：进入设置，勾选"TLS AllowInsecure"，保存后重试
   1. 
3. 修改 STUN 服务器：同上面的解决方案
4. 检查其他软件：确保关闭所有其他代理软件后重启电脑
5. 检查节点：选择其他节点重试
6. 重启设备：重启路由器和 Netch
7. 跳过绿点检查：如果后续 Quest3 能正常更新（进度条会走），可以不用管绿点

提示"找不到 VCRUNTIME140.dll"

搜索下载"Windows 常用运行库"并安装。

一、现象与环境

• Git Bash 终端卡顿：输入有明显延迟，命令执行后迟迟不返回提示符。
• 使用的是 zsh（配合 oh-my-zsh），启用了包括 z 在内的多个插件。
• 家目录出现了很多 .z 相关文件（z 插件的跳转数据库），怀疑数据库过大导致慢响应。

二、我的排查与解决过程

1) 先隔离配置：用干净的 zsh -f 启动

• zsh -f 会在不加载 ~/.zshrc 的前提下启动一个“空配置”的 zsh，能快速判断是否是配置或插件导致问题。
• 如果 zsh -f 下终端恢复顺畅，基本可以确定问题在 ~/.zshrc 或其引入的插件与脚本。

2) 定位“嫌疑插件”：移除 ~/.zshrc 中的 z 插件

• 打开 ~/.zshrc，从 plugins=(...) 中移除 z，保存退出，重新打开终端。
• 如果卡顿消失，进一步确认 z 插件就是主要原因。

3) 清理 z 插件数据库：删除家目录下的 .z 数据文件

• z 插件默认会在家目录存储路径权重数据库，文件名通常为 ~/.z（可能还有备份，比如 ~/.z.1 等）。

• 执行：

  rm -f ~/.z ~/.z.*
  

  注意：只删除 .z 及其备份，勿用宽泛的通配符误删其他以 .z 开头的配置文件（例如 ~/.zshrc、~/.zsh_history 等）。

4) 验证

• 再次启动 Git Bash，观察输入响应与命令执行返回。若明显恢复正常，则问题确认并解决。

三、更多可能导致终端卡顿的原因与优化方法

下面按层次列出常见瓶颈与处理策略。建议从“快速隔离”到“逐步优化”依次进行。

A. zsh 配置与插件层面

• 用 zsh -f 快速隔离：先确认卡顿是否源自 ~/.zshrc。

• 用内置性能分析：

  1. 在交互会话里执行：

     zmodload zsh/zprof
     source ~/.zshrc
     zprof
     

  2. 查看哪个函数或插件耗时最多，针对性优化或禁用。

• 精简/优化高开销插件：

  • zsh-autosuggestions：在超长历史或远程磁盘上可能放大延迟，必要时暂时禁用。
  • zsh-syntax-highlighting：对超长命令行或复杂高亮也可能造成卡顿，可移到 ~/.zshrc 最末加载或暂时禁用。
  • git 相关主题/段：提示符中显示仓库状态若每次刷新都做代价高的检测，易导致卡顿（详见下一节）。

• 清理与限制缓存/历史：

  • 删除过期的 ~/.zcompdump* 文件，让补全缓存重新生成：

    rm -f ~/.zcompdump*
    compinit -C
    

  • 限制历史大小，避免历史过大：

    export HISTSIZE=5000
    export SAVEHIST=5000
    

  • 必要时压缩或清理 ~/.zsh_history（先备份，再用专门工具或谨慎操作）。

• 优化补全与缓存（选做）：

  # 开启补全缓存（需确保缓存目录存在）
  zstyle ':completion:*' use-cache on
  zstyle ':completion:*' cache-path $HOME/.zsh/cache
  

• 控制 PATH 长度与重复项：超长 PATH 或大量网络路径会增加命令解析成本，去重并移除不必要条目。

• 跳转插件替代：如果依赖频繁路径跳转，可以考虑更高性能的 zoxide（Rust 实现，跨平台），或使用 fzf + cd 组合实现快速导航。

B. Git 状态/提示符层面（对大型仓库尤其重要）

• 减少提示符的 Git 状态开销：

  • 如果使用 oh-my-zsh 的 git 主题段，可以只显示分支名，不显示“脏状态”（新增/删除/未跟踪），显著减少每次刷新调用：

    export DISABLE_UNTRACKED_FILES_DIRTY="true"
    

  • 避免在 PROMPT 或 RPROMPT 中触发完整的 git status（尤其是有大量未跟踪文件时）。

• 提升 Git 的基础性能（全局设置，温和安全）：

  git config --global core.preloadIndex true
  git config --global core.fscache true
  git config --global gc.writeCommitGraph true
  git maintenance start
  

  说明：

  • core.preloadIndex 与 core.fscache 常见于 Git for Windows 的加速选项（新版本多为默认开启，显式配置更稳妥）。
  • 写入 commit-graph 与开启维护任务，可以加速多种 Git 操作（包括 status、log 等），对大仓库尤为明显。

• 仅在确定版本支持的情况下考虑文件监控（fsmonitor）：新版本 Git 在 Windows 上逐步完善内置 FS 监控特性，能减少反复扫描文件系统的成本。建议升级到较新的 Git for Windows 后再查阅对应版本说明开启；旧版或不支持时不要启用。

C. 终端/系统层面（Windows）

• 升级工具与组件：
  • 升级到最新的 Git for Windows。
  • 如果使用外部终端（如 Windows Terminal），留意 ConPTY 后端的兼容参数；不同设置在部分环境下会影响交互流畅度。
• 杀毒/安全软件与索引扫描：
  • 为 C:\Program Files\Git\ 安装目录与主要仓库路径添加实时扫描排除规则，避免每次命令触发大量 I/O 扫描。
  • 避免在网络盘、同步盘（如 OneDrive）或被系统索引服务重度扫描的目录中工作。
• 字体与渲染：
  • 某些 Nerd Font 或高开销渲染配置在低配环境下也会造成刷新卡顿，可换用常规字体测试。

四、快速排查与操作清单（可直接拿来用）

• 干净启动，判断是否为配置问题：

  zsh -f
  

• 性能画像（找出最慢的函数/插件）：

  zmodload zsh/zprof
  source ~/.zshrc
  zprof
  

• 移除 z 插件，并清理数据库：

  1. 编辑 ~/.zshrc，从 plugins=(...) 中删除 z；

  2. 删除数据库文件：

     rm -f ~/.z ~/.z.*
     

• 限制 Git 状态显示开销（oh-my-zsh）：

  export DISABLE_UNTRACKED_FILES_DIRTY="true"
  

• 提升 Git 基础性能（全局）：

  git config --global core.preloadIndex true
  git config --global core.fscache true
  git config --global gc.writeCommitGraph true
  git maintenance start
  

• 清理补全缓存并快速初始化：

  rm -f ~/.zcompdump*
  compinit -C
  

五、结语

这次卡顿的根因是 z 插件的路径数据库过大，移除插件并清理 .z 数据后问题即刻消失。更通用的经验是：先用 zsh -f 快速隔离，再用 zprof 定位耗时点

useradd -m user

修改默认shell为bash

sudo usermod -s /bin/bash user

添加用户到sudoers

sudo usermod -aG sudo user

立即生效配置

sudo newgrp sudo

修改用户密码

sudo passwd user

一键安装Docker

curl -fsSL https://cdn.jsdelivr.net/gh/muzihuaner/docker-install@master/install.sh -o install-docker.sh
sh install-docker.sh

配置镜像仓库

echo '{"registry-mirrors": ["https://docker.1ms.run"]}' | sudo tee /etc/docker/daemon.json > /dev/null
        systemctl daemon-reload
        systemctl restart docker

添加当前用户到docker组，避免每次使用docker命令时都需要sudo

sudo usermod -aG docker $USER

生效配置

newgrp docker

常见问题

安卓客户端登录密码错误 password invalid

确保hosts中的域名都能够被正常解析。

127.0.0.1 us-or-rly101.zwift.com 
127.0.0.1 secure.zwift.com 
127.0.0.1 cdn.zwift.com 

安卓设备可以下载应用Termux，可以使用ping命令检查域名是否能够被正常解析。

ping us-or-rly101.zwift.com
ping secure.zwift.com
ping cdn.zwift.com

一定到注意每个域名都测试一遍，之前有遇到过只有部分域名能够被正常解析的情况。如果发现部分域名能够被正常解析，而部分域名不能被正常解析，可以尝试使用txt编辑工具，比如txtpad，不要使用WPS，Microsoft Word等工具来编辑，这些工具可能会自动将域名转换为其他格式，导致无法被正常解析。用txtpad编辑后，保存为hosts.txt文件到能找到的位置，然后重新使用ping命令检查域名是否能够被正常解析。

某天看到Strava上自己的骑行轨迹，仓鼠的天性开始显露，既然能记录骑行的轨迹，为啥不把开车轨迹，步行轨迹都记录了？虽然早就听说了世界迷雾（Fog of World），但是因为走过的地方并不多，再加上安装过程比较复杂，所以一直没有尝试。现在看到骑行的地方越来越多，世界迷雾（Fog of World）的诱惑越来越大，于是开始折腾。

使用这个软件就不多说了，反正倒腾Google Pay就捣鼓了好久，又花了20刀乐买了这个软件。

虽然这个软件本身就是自带轨迹记录功能，但是使用手机导航的都知道，任何需要GPS功能的软件都是耗电大户，让这个软件常驻后台显然不能接受，一次偶然的机会，看到了这个设备，原来可以通过外置GPS记录轨迹，于是开始折腾。

探险家V900 GPS轨迹记录器

一个快20年前的产品，早已经停产，目前只能找到它的升级版V990以及性能更好的产品，但是价格也贵了不少。即使现在能找到在售的V990，价格也要500块，还是没有舍得。只能在闲鱼上淘一下，140块淘了一个品相还不错的V900。

因为对GPS硬件一窍不通，也不知道这个规格里的性能如何，只是想当然觉得专用的GPS记录器应该至少比手机强吧，但是东西到手只能感叹一句，技术进步太快了。

这玩意只能获取GPS信号，但是现在最廉价的手机都能支持多种定位方式，包括GPS，北斗，GLONASS等等信号了，这意味它获取定位的精度和速度都远远不如手机。

在室内定位了很久都没有定位成功，又专门到楼下空地还是无法定位，最终只能放弃，退回卖家，但是卖家也可能觉得是老古董了，估计很难卖出去，最终答应20块钱卖给我。我心想20块钱买个曾经500块的玩具，也挺划算的，于是就收下了。既然能开机，说明硬件应该没问题，应该还是能用的。

折腾过程

无法定位

因为设备很久没有开机定位了，所以相当于冷启动，通常获取GPS信号时间就会很久，之前买新的码表时就会遇到这种情况，第一次定位花了很久，以为设备坏了，后来定位成功一次后，后续定位就很快了。于是我又找了一块广场空地开始定位，这次果然定位成功了。

所以想要解决定位问题，首先不能在室内，室内因为混凝土遮挡信号，几乎无法定位成功，第一次定位时最好找个没有遮挡的空地，3-5分钟基本上能定位成功。

无法记录轨迹

这个问题包括插入内存卡后，开机后自动关机，定位成功后设备发出急促的哔哔哔声音，这些都是因为内存卡分区格式问题导致的。

因为这是快20年前的产品，那时候的内存卡大多还是4G以下的内存，文件系统还是FAT格式，现在想要买一个4G以下的内存卡都很难了，所以能见到的大部分内存卡都是无法直接在这个设备上使用，必须格式化成FAT格式。所以最好找一个小容量的卡，如果是4G以下的卡，通常可以在电脑上直接格式化为FAT或者FAT16，如果大于4G的卡，那就需要专门的软件来格式化了，并且格式化之后的容量最大就只有4G，所以最好买一个小容量卡。

格式化的工具和步骤可以参考这个链接：How to record tracks in V-990/V-900 with a MicroSD card (Capacity above 4G)。虽然是老古董产品，但是这个常见的售后支持做的还是很到位的，这么多年都还保留了所有产品的文档和相关工具。

最终卡信息如下：

产品文档链接：支持和下载

使用蓝牙连接设备

这个功能当初开发出来应该是为了给一些软件提供第三方的导航功能的，但是现在导航工具已经触手可得，这个功能就没什么用了。如果你想尝试一下这个功能，可以下载一个Bluetooth GPS软件，Bluetooth GPS针对于Android - 从Uptodown上下载APK来连接设备。

链接过程如下：

1. 长按开机键开机，自动进入蓝牙模式，蓝牙灯闪烁
2. 打开手机蓝牙，搜索设备，找到设备后点击连接，设备名称为Columbus GPS
3. 输入匹配码0000连接设备
4. 打开软件选择Columbus GPS，点击连接
5. 连接成功后，软件会显示设备信息，包括经纬度，速度，海拔等

轨迹实测

蓝色是佳明Forerunner 255的运动轨迹，红色是V900的轨迹，可以看到V900的性能在今天来说完全不够看了，漂移严重，并且海拔信息几乎不可用，这么点距离海拔爬升200多，在海宁这种大平原上，走一天都爬不了这么高。

Strava Statistics 是一个自托管工具，利用 Strava 数据生成个人运动统计，支持 Docker 部署，提供丰富的可视化分析。下面介绍如何使用 Docker Compose 部署。

申请 Strava 的 API 权限

在ZwiftOffline中也需要用到 API 权限，因为不同应用程序也不冲突，懒得再重新申请，所以以下填的信息使用的 ZwiftOffline 的 API 权限。

登录Strava，申请 API，获取Client ID和Client Secret。

填写内容可以参考下图：

其中授权回调域填写：launcher.zwift.com

申请完成后会得到下面的信息：

将下面链接中的client_id值换成上图中的客户 ID，然后浏览器中访问这个链接：

http://www.strava.com/oauth/authorize?client_id=xxxxxxx&response_type=code&redirect_uri=http://localhost/exchange_token&approval_prompt=force&scope=activity:read_all

点击授权：

此时跳转到一个无法访问的网页，将地址栏中的code值记录下来，后面需要用到：

需要用这个code发起一个 cURL 请求得到refresh_token，具体做法是在命令行终端中执行下面的命令：

	curl -X POST https://www.strava.com/oauth/token \
	-F client_id=YOURCLIENTID \
	-F client_secret=YOURCLIENTSECRET \
	-F code=AUTHORIZATIONCODE \
	-F grant_type=authorization_code

• client_id值替换为申请得到的客户ID
• client_secret值替换为申请得到的客户端密钥
• code替换为上一步浏览器中得到的code

执行成功后可以得到下面的返回信息，需要将返回值中的refresh_token和access_token记录下来，后面需要用到：

{"token_type":"Bearer","expires_at":1740213400,"expires_in":21600,"refresh_token":"123456789123456789","access_token":"123456789123456789","athlete":{"id":117756825,"username":"dunky_zhang","resource_state":2,"firstname":"Dominic","lastname":"Zhang","bio":"骑行小白","city":"","state":"","country":null,"sex":"M","premium":true,"summit":true,"created_at":"2023-05-10T13:54:32Z","updated_at":"2025-02-06T05:29:52Z","badge_type_id":1,"weight":66.0,"profile_medium":"https://dgalywyr863hv.cloudfront.net/pictures/athletes/117756825/32138099/2/medium.jpg","profile":"https://dgalywyr863hv.cloudfront.net/pictures/athletes/117756825/32138099/2/large.jpg","friend":null,"follower":null}}#

Docker Compose 部署 Strava Statistics

创建目录用于存放 Strava Statistics 的配置文件

mkdir statistics-for-strava
cd statistics-for-strava

创建 docker-compose.yml 文件

touch docker-compose.yml

编辑 docker-compose.yml 文件，填入以下内容：

services:
  app:
    image: robiningelbrecht/strava-statistics:latest
    volumes:
      - ./build:/var/www/build
      - ./storage/database:/var/www/storage/database
      - ./storage/files:/var/www/storage/files
    env_file: ./.env
    ports:
      - 8080:8080
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      # 因为 Strava 的 API 需要代理访问，所以下面设置了我的代理地址，请你根据自己的代理地址进行设置
      - http_proxy=http://192.168.1.9:7890
      - https_proxy=http://192.168.1.9:7890
      - all_proxy=socks5://192.168.1.9:7891

创建 .env 文件

touch .env

编辑 .env 文件，填入以下内容：

# 应用程序将托管的URL。此URL将用于清单文件中。
# 这将允许您将Web应用程序作为原生应用程序安装到您的设备上。
MANIFEST_APP_URL=http://localhost:8080/
# 您的Strava应用程序的客户端ID。
STRAVA_CLIENT_ID=xxxxxxx
# 您的Strava应用程序的客户端密钥。
STRAVA_CLIENT_SECRET=xxxxxxxxxxxxxx
# 您的Strava应用程序的刷新令牌。在上一步获取到的
STRAVA_REFRESH_TOKEN=xxxxxxxxxxxxxx
# Strava API有限速限制（https://github.com/robiningelbrecht/strava-statistics/wiki），
# 为了确保我们不会达到限速，我们希望限制每次导入处理的新活动数量。
# 考虑到每天有1000次请求限制，并且导入一个新活动最多可能需要3次API调用，250应该是一个安全的数字。
NUMBER_OF_NEW_ACTIVITIES_TO_PROCESS_PER_IMPORT=250
# 定期运行导入和HTML构建的计划。留空以禁用定期导入。
# 默认计划为每天凌晨04:05运行一次。如果您不知道什么是cron表达式，请勿更改此项。
# 请确保不要过于频繁地运行导入，以避免达到Strava API的限速。每天一次应该足够。
IMPORT_AND_BUILD_SCHEDULE="5 4 * * *"
# 设置用于计划的时区
# 有效的时区可以在此处找到（TZ标识符列）：https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
TZ=Asia/Shanghai

# 允许的选项：en_US、fr_FR 或 nl_BE
LOCALE=en_US
# 允许的选项：metric（公制）或 imperial（英制）
UNIT_SYSTEM=metric
# 渲染应用程序时使用的时间格式
# 允许的格式：24 或 12（包括AM和PM）
TIME_FORMAT=24
# 渲染应用程序时使用的日期格式
# 允许的格式：DAY-MONTH-YEAR（日-月-年）或 MONTH-DAY-YEAR（月-日-年）
DATE_FORMAT=DAY-MONTH-YEAR
# 要导入的运动类型。留空以导入所有运动类型。
# 通过此列表，您还可以决定运动类型的渲染顺序。
# 完整的允许选项列表可在以下地址找到：https://github.com/robiningelbrecht/strava-statistics/wiki/Supported-sport-types/
SPORT_TYPES_TO_IMPORT='[]'
# 您的生日。需要用于计算心率区间。
ATHLETE_BIRTHDAY=1999-01-01
# 体重历史（单位为千克或磅，取决于UNIT_SYSTEM）。需要用于计算相对功率重量比（w/kg）。
# 查看更多信息：https://github.com/robiningelbrecht/strava-statistics/wiki
ATHLETE_WEIGHTS='{
    "1970-01-01": 68
}'

# FTP（功能阈值功率）历史。需要用于计算活动压力水平。
# 查看更多信息：https://github.com/robiningelbrecht/strava-statistics/wiki
FTP_VALUES='{
    "2024-12-12": 235
}'
# 包含ntfy主题的完整URL。此主题将用于在新的HTML构建运行时通知您。
# 留空以禁用通知。
NTFY_URL=''
# 在导入期间要跳过的活动ID数组。
# 这允许您在导入时跳过特定活动。
ACTIVITIES_TO_SKIP_DURING_IMPORT='[]'

# 创建/拥有由strava-statistics管理的文件的UID和GID
# 可能仅在Linux主机上需要，详见Wiki中的文件权限部分
#PUID=
#PGID=

开始导入数据：

• 启动容器

  docker-compose up -d
  

• 导入数据

  docker compose exec App bin/console app:strava:import-data
  docker compose exec App bin/console app:strava:build-files
  

  导入过程非常非常慢，因为需要挨个数据获取，并且很容易出错，如果出错了，需要先关闭容器，然后重新导入。以下是导入成功的截图：

  

• 访问 localhost:8080 查看数据

常见问题

401 Unauthorized

.env中的STRAVA_REFRESH_TOKEN可能过期，需要重新获取。又或者压根就忘记了获取refresh_token，需要重新获取。

Failed to connect to nominatim.openstreetmap.org

因为需要生成一些地图热点信息，所以需要访问 nominatim.openstreetmap.org，所以需要配置代理。

Tring to calculate the relative power for activity

因为需要计算相对功率重量比（w/kg），所以需要配置体重历史。如果发现某个活动的时间点没有配置体重信息就会报这个错。看看.env中的ATHLETE_WEIGHTS是否配置正确。我建议直接修改成我提供的数据，也就是从 1970 年开始都是当前的体重。因为我尝试配置了自己的体重历史，但是一直报错，所以直接改成了这个。

Looks like you still need to import your strava data

如果你只执行了docker-compose up -d，而没有执行导入数据的命令，那么就会出现这个错误。需要执行导入数据的命令。如果你已经导入成功了，如果还报这个错，就需要重启一下容器。

ZwiftOffline是一个开源社区自制的 Zwift 的 server 端，可以在没有网络的情况下进行 Zwift 课程或路线训练，多平台支持。

本教程将详细介绍如何在 Windows 系统上安装和配置 Zwift 单机版，包括基础安装、账号配置、Strava 同步、训练课程上传以及移动端 Companion 配置等完整流程。

一、准备工作

1.1 下载必要文件

1. ZwiftOffline 主程序

   • 从GitHub Release 页面下载最新的 zoffline 发布版（.exe文件）

2. 配置辅助工具

   • 从GitHub Release下载zoffline-helper.zip配置脚本文件

3. Zwift 官方客户端

   • 前往Zwift 官网，拉到页面底部，下载并安装 Zwift 软件
   • 重要：记住安装路径，后续配置需要用到（例如：C:\Program Files (x86)\Zwift）

1.2 创建运行目录

创建一个目录用于存放 ZwiftOffline 相关文件，例如新建zwiftoffline目录。

二、基础安装与配置

2.1 初始化 ZwiftOffline

1. 将下载的zoffline.exe文件保存到zwiftoffline目录
2. 运行zoffline.exe，程序会在同目录下自动创建storage目录（用于保存 Zwift 进度）
3. 看到storage目录生成后，按Ctrl+C关闭 zoffline，稍后进行配置

2.2 安装并更新 Zwift 客户端

1. 运行刚安装的 Zwift 程序，客户端会开始更新游戏本体
   • ⚠️ 重要提示：必须在配置网络之前完成此步骤，因为后续配置会修改 hosts 文件，导致无法连接到 Zwift 服务器下载游戏本体

2.3 配置网络连接

1. 将下载的zoffline-helper.zip解压到zwiftoffline目录
2. 进入zwiftoffline/zoffline-helper目录
3. 右键点击configure_client.bat，选择以管理员身份运行
4. 脚本会自动配置 zoffline，期间会弹窗让你选择 Zwift 安装目录（即之前记住的路径）

5. 配置完成后，会显示如下结果：

2.4 启动并验证

1. 进入zwiftoffline目录，双击运行zoffline.exe（文件名可能因版本而异，如zoffline_1.0.140279.exe）

2. 启动原版 Zwift 程序，检查登录界面
   • 成功标志：显示 ZwiftOffline 的登录页面（如下图）

• 失败标志：如果显示官方原版登录界面，说明配置失败

3. ⚠️ 重要提示：
   • 如果显示的是原版登录页面，检查是否开启了代理，关闭代理后重试
   • 将输入法切换为微软英文输入法，点击Start Zwift开始游戏
   • 使用搜狗输入法等第三方输入法可能会卡在登录页面

三、高级配置

3.1 同步原有账号信息

如果不配置此项，使用 Zwift offline 时会显示为新账号，而不是你原来的账号信息。

配置步骤：

1. 在登录页面点击设置按钮进入设置界面

2. 填写你的 Zwift 邮箱和密码，勾选所有选项，点击 Submit 提交

3. 配置完成后，再次登录 Zwift 时就会显示为原来的账号了

3.2 配置 Strava 自动上传

3.2.1 申请 Strava API

1. 登录Strava API 设置页面
2. 创建新应用，填写以下信息：
   • 应用名称：自定义（如：ZwiftOffline）
   • 类别：其他
   • 授权回调域：launcher.zwift.com
   • 网站：可留空或填写个人网站

3. 申请完成后，记录下Client ID和Client Secret

3.2.2 在 ZwiftOffline 中配置 Strava

1. 在登录页面进入设置，填写Client ID和Client Secret

点击Submit提交：

3.2.3 授权 Strava 访问

这一步可以省略，如果通过上面的步骤没法上传，再尝试这个步骤手动配置

1. 右键以管理员身份运行zoffline-helper/disable_zoffline.bat，清除 hosts 配置

2. 在命令行中运行以下命令（替换CLIENT_ID和CLIENT_SECRET为你的实际值）：

   zoffline-helper/strava_auth.exe --client-id CLIENT_ID --client-secret CLIENT_SECRET
   

3. 浏览器会自动打开或手动访问localhost:8000进行授权

4. 授权完成后，将生成的strava_token.txt文件移动到storage/1目录下
5. 右键以管理员身份运行zoffline-helper/configure_client.bat，重新配置 hosts

3.3 上传自定义训练课程

如果你习惯在 Intervals ICU 等平台创建训练课程，可以手动上传到 Zwift 单机版。

上传步骤：

1. 将你的.zwo训练课程文件保存到以下目录：

   Documents/Zwift/Workouts/1
   

2. ⚠️ 注意：不是zwiftoffline\storage\1\customworkouts目录，如果放错位置会导致课程无法上传

3.4 配置 Garmin Connect

Garmin Connect 可以同步你的 Zwift 活动数据到 Garmin 设备。

3.4.1 配置账号

1. PC 端配置

   • 在 ZwiftOffline 登录窗口点击"Settings - Garmin"按钮
   • 输入你的 Garmin Connect 账号和密码

2. 安卓端配置

   • 访问 https://<zoffline_ip>/garmin/zoffline/
   • 输入你的 Garmin Connect 账号和密码
   • 将<zoffline_ip>替换为运行 zoffline 的电脑 IP 地址

3.4.2 多因素认证（MFA）

如果你的账号启用了多因素认证，需要额外配置：

1. 使用 Python 脚本（推荐）

   • 运行garmin_auth.py脚本
   • 脚本会在运行目录下生成garth文件夹
   • 将garth文件夹移动到storage/1目录下

2. 使用 Windows 可执行文件

   • 如果未安装 Python，可以从zoffline-helper Release 页面下载garmin_auth.exe
   • 运行garmin_auth.exe，同样会生成garth文件夹
   • 将garth文件夹移动到storage/1目录下

3.5 配置 Intervals.icu

Intervals.icu 是一个强大的训练分析平台，可以同步 Zwift 活动数据。

3.5.1 获取 API 凭证

1. 登录 Intervals.icu 设置页面
2. 进入"Developer Settings"（开发者设置）部分
3. 复制以下信息：
   • Athlete ID（运动员 ID）
   • API Key（API 密钥）

3.5.2 配置账号

1. PC 端配置

   • 在 ZwiftOffline 登录窗口点击"Settings - Intervals"按钮
   • 输入之前复制的 Athlete ID 和 API Key

2. 安卓端配置

   • 访问 https://<zoffline_ip>/intervals/zoffline/
   • 输入 Athlete ID 和 API Key
   • 将<zoffline_ip>替换为运行 zoffline 的电脑 IP 地址

3.6 启用多人游戏

多人游戏功能允许多个用户同时连接到同一个 zoffline 服务器进行骑行。

3.6.1 基本配置

1. 在storage目录下创建multiplayer.txt文件（文件内容为空）

3.6.2 远程服务器配置

如果 zoffline 运行在与 Zwift 客户端不同的 PC 上：

1. 在storage目录下创建server-ip.txt文件
2. 文件内容填写运行 zoffline 的 PC 的 IP 地址
3. 端口要求：确保以下端口在运行 zoffline 的 PC 上开放：
   • TCP 端口：80, 443, 3025
   • UDP 端口：3024

3.6.3 创建账号

1. 启动 Zwift，创建新账号
2. ⚠️ 注意：此账号仅存在于你的 zoffline 服务器上，与官方 Zwift 账号无关

3.6.4 启用密码重置功能（可选）

1. 在storage目录下创建gmail_credentials.txt文件
2. 文件内容格式：

<gmail 账号>
<应用密码>
<恢复 URL 主机（可选）>

3. 获取应用密码：
   • 访问 https://security.google.com/settings/security/apppasswords
   • 创建应用密码，允许服务器登录
   • 将生成的应用密码填入文件第二行
4. 恢复 URL 主机（可选）：
   • 第三行可以填写恢复 URL 的主机地址
   • 如果不填写，将使用服务器 IP 地址作为默认值

3.7 启用 Ghosts（幽灵）

Ghosts 功能可以保存你之前的骑行记录，并在相同路线上显示为"幽灵"与你一起骑行。

3.7.1 启用功能

1. PC 端

   • 在 zoffline 启动器窗口中勾选"Enable ghosts"

2. 安卓端

   • 访问 https://<zoffline_ip>/user/zoffline/
   • 勾选"Enable ghosts"
   • 点击"Start Zwift"保存设置

3.7.2 使用说明

1. 保存幽灵：当你保存活动时，幽灵会自动保存在storage/<player_id>/ghosts/<world>/<route>目录下
2. 加载幽灵：下次骑行相同路线时，幽灵会自动加载
3. 重新编组：在聊天中输入.regroup命令可以重新编组幽灵

3.7.3 自定义装备

1. 在storage目录下创建ghost_profile.txt文件
2. 可以使用find_equip.py脚本来自动填充此文件

3.8 启用 Bots（机器人）

Bots 功能可以将保存的幽灵转换为持续骑行的机器人，无论你选择什么路线，它们都会继续骑行。

3.8.1 启用功能

1. 在storage目录下创建enable_bots.txt文件
2. 可选：文件内容可以包含一个倍数（如：2表示双倍机器人数量）
   • ⚠️ 警告：如果机器人数量过多，可能导致性能问题或功能失效

3.8.2 控制命令

在聊天中使用以下命令控制机器人：

• .group：编组机器人
• .groupall：编组所有机器人（包括使用倍数时的重复机器人）
• .autogroup：自动编组（当你改变路线时）
• .autogroupall：自动编组所有机器人
• .stopautogroup：停止自动编组
• .disperse：随机化机器人位置

3.8.3 自定义机器人

1. 在storage目录下创建bot.txt文件
2. 可以自定义机器人的名称、国籍和装备
3. 可以使用get_pro_names.py脚本来自动填充此文件
4. 随机机器人：如果需要随机机器人，可以参考zoffline-bots 仓库

3.9 配置 RoboPacers（机器人配速员）

RoboPacers 是使用功率模拟器保存的幽灵，可以创建完美的循环配速员。

3.9.1 获取 RoboPacers

1. 可以从zoffline-bots 仓库下载预制的 RoboPacers

3.9.2 创建要求

要创建可用的 RoboPacer，需要满足以下条件：

1. 更新频率：必须使用 1 秒的更新频率录制（默认是 3 秒）
2. 循环要求：活动必须从同一位置和速度开始和结束，否则机器人无法平滑循环
3. 配置文件要求：
   • 必须包含唯一的玩家 ID
   • 必须包含路线 ID
   • 这样当你加入机器人时，会在交叉路口走相同的转弯

3.9.3 编辑工具

1. bot_editor.py 脚本：可以用于修改以下文件：
   • profile.bin：设置名称、玩家 ID 和路线 ID
   • route.bin：裁剪多余的点以创建完美循环

3.9.4 创建动态 RoboPacer

要创建动态 RoboPacer（在上坡时增加功率，下坡时减少功率）：

1. 使用 standalone_power.py 脚本
2. 硬件要求：
   • 2 个 ANT 适配器
   • python-ant
   • PowerMeterTx.py

3.10 使用 Bookmarks（书签）

书签功能可以保存你的位置，方便快速跳转到特定地点。

3.10.1 自动保存书签

当你完成活动时，你的最后位置会自动保存为书签。

3.10.2 手动保存书签

在聊天中使用以下命令保存书签：

.bookmark <名称>

例如：.bookmark 起点

3.10.3 使用书签

1. 从书签开始新活动：

   • 在主页屏幕选择"Join a Zwifter"
   • 选择你想要的书签

2. 传送到书签：

   • 使用操作栏上的传送图标
   • 选择目标书签进行传送

3.11 启用历史排行榜

历史排行榜功能可以覆盖 60 分钟的实时结果和 90 天的个人记录，显示所有时间的最佳成绩。

3.11.1 启用功能

1. 在storage目录下创建all_time_leaderboards.txt文件（文件内容可以为空）