npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

code-server-sync

v0.1.3

Published

经 code-server 已登录通道,在本机与云主机之间同步项目代码

Readme

cs-sync

cs-sync 在本机目录与运行 code-server 的云主机目录之间同步代码。

通道使用 code-server 已经登录的 /proxy/<端口>/,不另外开放公网入口。云端用 cs-sync recv 启动接收进程。

本机可以是 Windows 或 macOS。云端接收进程运行在 Linux 上。

适合谁

适合需要在本机编辑,并把代码同步到已经登录的 code-server 云主机上。

它不替代编辑器、编译器或部署流水线。

前提

本机(Windows 或 macOS):

  • Node.js 18 及以上
  • Python 3.9 及以上。Windows 上使用 py -3 或 python,macOS 上使用 python3
  • Git。整份同步前的暂存、行级 diff 和 sync 都会用到

云端(Linux):

  • Node.js 18 及以上
  • Python 3.9 及以上,使用 python3
  • Git。整份同步前的暂存、行级 diff 和 sync 都会用到

安装

本机和云端各执行一次(在各自的终端里):

npm install -g code-server-sync
cs-sync --help
cs-sync --version

不安装到全局时,在要使用的那一侧执行:

npx code-server-sync --help

命令在哪执行

日常要用的 cs-sync 子命令都在本机终端执行:init、login、cookie、token、list、remove、doctor、to-cloud、to-local、diff-to-cloud、diff-to-local、sync、self-test。

只在云端 Linux 终端执行的是 cs-sync recv ...。这条命令由本机的 init 或 token 打印出来,原样粘贴到 code-server 终端。安装和升级 code-server-sync 时,本机和云端各自执行一次对应的 npm 命令。

一次完整使用会经过什么

  1. 在本机和云端都安装 code-server-sync
  2. 在本机登记本机目录、云端目录和 code-server 地址
  3. 在本机写入 code-server 登录态
  4. 在本机用 token 打印云端接收命令
  5. 把打印出的 cs-sync recv ... 贴到云端终端执行
  6. 在本机用 doctor 检查通道
  7. 在本机先 --dry-run,再正式同步

| 步骤 | 在哪执行 | 命令 | 结果 | |------|----------|------|------| | 登记 | 本机 | cs-sync init | 生成项目令牌和接收端口,并打印云端启动命令 | | 登录 | 本机 | cs-sync login 或 cs-sync cookie | 把 code-server 登录态记到本机配置 | | 打印命令 | 本机 | cs-sync token | 再次打印要贴到云端的 cs-sync recv ... | | 启动接收 | 云端 | cs-sync recv ... | 云端开始在该端口接收 | | 检查 | 本机 | cs-sync doctor | 确认代理、令牌和路径校验 | | 演练 | 本机 | cs-sync to-cloud --dry-run | 只列出将要发生的变化 | | 同步 | 本机 | cs-sync to-cloud 或 cs-sync sync | 按所选方式写入 |

在本机的 localRoot 目录内运行时可以省略 --name。

最短上手

下面的 init、login、token、doctor、to-cloud、sync 都在本机执行。唯一要贴到云端终端的,是 token 打印出来的那一行 cs-sync recv ...。

本机执行。 macOS(bash / zsh)用 \ 续行:

cs-sync init \
  --name 我的项目 \
  --local /本机/项目目录 \
  --remote /云端/绝对路径 \
  --base https://code-server主机:端口

本机执行。 Windows PowerShell 用反引号 ` 续行,反引号必须是该行最后一个字符。--local 写本机路径:

cs-sync init `
  --name 我的项目 `
  --local C:\work\demo `
  --remote /云端/绝对路径 `
  --base https://code-server主机:端口

仍在本机执行:

cs-sync login

cs-sync token --name 我的项目

把 token 打印的那一行贴到云端 code-server 终端。云端执行:

cs-sync recv --root '/云端/绝对路径' --token '…' --port 27182

回到本机执行:

cs-sync doctor --name 我的项目
cs-sync to-cloud --name 我的项目 --dry-run
cs-sync to-cloud --name 我的项目
cs-sync sync --name 我的项目

Windows 上 --local 使用本机路径,例如 C:\work\demo。--remote 始终是云端 Linux 绝对路径。token 打印的引号按云端 shell 转义,直接粘贴到云端终端。

按意图选择命令

下面每一条都在本机执行。执行前,云端终端里要已经在跑 cs-sync recv。

我要检查通道

本机执行:

cs-sync doctor --name 我的项目

我要把本机整份覆盖到云端同名路径

本机执行:

cs-sync to-cloud --name 我的项目

我要把云端整份覆盖到本机同名路径

本机执行:

cs-sync to-local --name 我的项目

我只想把本机尚未提交的行级改动推上去

本机执行:

cs-sync diff-to-cloud --name 我的项目

我只想把云端尚未提交的行级改动拉下来

本机执行:

cs-sync diff-to-local --name 我的项目

我要在保存之后双向同步启动后的增量

本机执行:

cs-sync sync --name 我的项目

三种同步

to-cloud、to-local、diff-to-cloud、diff-to-local、sync 都在本机执行。云端只负责已经启动的 cs-sync recv。

整份:to-cloud / to-local

按相对路径扫描,用 SHA-256 比较内容,相同则跳过。覆盖同名文件,对端独有的文件保留。正式执行前,对即将被覆盖的一侧执行 git add -A,把当前改动放进 index。--dry-run 不会暂存。

默认同步忽略:.git、.agents、.idea、node_modules、dist、build、coverage、.next、.nuxt、.turbo、.cache、tmp、__pycache__、.venv、venv、vendor、.gradle、CMakeFiles、.dart_tool。

init 会把当时的目录名列表写入项目配置的 ignoreDirs。已经建好的项目不会自动改用新列表。要改用当前内置列表,删掉该字段;要少忽略几项,直接编辑这份列表。

扫描时会跳过约 32MB 以上的单个文件。上传和下载使用同一个大小限制,超过会拒绝。

行级:diff-to-cloud / diff-to-local

收集相对 HEAD 的 git diff,没有 HEAD 时使用已暂存内容,并包含未跟踪的新文件。对端在临时目录用 git apply 试算后再写入。合不上则跳过该文件,保留对端原内容。二进制、对端已经存在的「新增」和补丁冲突记为失败或冲突。

监视:sync

启动时扫描本机并读取云端清单,记下基线。两边当时已经不一致的内容只记基线,启动前的差异留给 to-* 或 diff-*。之后只同步启动后的保存。

本地改动按相对上次已同步内容的行级 diff 推到云端。云端改动先试行级补丁,对不上再做三路合并。真冲突时保留这一侧已有内容,并打印提示。二进制不能按行同步。

| 日志 | 含义 | |------|------| | 本地改动 | 本机先改,并已同步到云端。删除时带「(删除)」 | | 本地写入 | 因为云端变更,本机文件被写入或删除 | | 云端改动 | 云端工作区先出现变更 | | 云端写入 | 因为本机同步,云端文件被写入或删除 |

云端日志仍是旧文案时,在云端升级 code-server-sync 并重启 cs-sync recv。本机上正在跑的 cs-sync sync 也要重新启动。

.cs-syncignore

在本机目录或云端目录放置 .cs-syncignore,语法与 gitignore 类似:*、?、**、目录尾 /、# 注释、! 否定。

它和内置忽略取并集,命中任一即跳过。! 不能抵消内置忽略,例如 !node_modules 无效。各端读取自己目录下的这份文件。扫描、整份同步、行级同步、sync 和 --dry-run 都会用它。

--dry-run

在本机加在 to-cloud、to-local、diff-to-cloud、diff-to-local、sync 后面。

不会执行 git add -A,不会调用云端暂存,不会写入或删除项目目录中的文件,不会把补丁落到工作区,也不会推送忽略规则。sync --dry-run 不进入持续监视,打印当前双边差异后退出。

会做连通检查,并只读读取云端清单。行级预览可能只读拉取对端内容,用来判断是相同跳过还是能够合入。

清单标签包括:add、modify、delete、skip-same、conflict、binary、local-only、remote-only。

命令一览

除 recv 外,下表命令都在本机终端执行。recv 只在云端 Linux 终端执行。

| 命令 | 在哪执行 | 作用 | |------|----------|------| | init | 本机 | 登记项目,生成令牌并分配端口 | | list / remove | 本机 | 列出或删除映射,不删除目录里的代码 | | login / cookie | 本机 | 写入 code-server 登录态,所有项目共用 | | token | 本机 | 打印要贴到云端执行的 recv 启动命令 | | doctor | 本机 | 检查代理、令牌和路径校验 | | to-cloud | 本机 | 云端先 git add -A,再用本机文件覆盖云端同名路径 | | to-local | 本机 | 本机先 git add -A,再用云端文件覆盖本机同名路径 | | diff-to-cloud | 本机 | 云端先暂存,再把本机 git diff 行级推到云端;合不上则跳过 | | diff-to-local | 本机 | 本机先暂存,再把云端 git diff 行级拉到本机 | | sync | 本机 | 记下基线后,按行级增量与三路合并双向同步之后的保存 | | recv | 云端 | 在云端 Linux 上接收本机发来的同步请求 | | self-test | 本机 | 在本机临时目录检查协议,不连接真实 code-server |

同步类命令都支持 --dry-run。全局可选 --config /某/项目.json。cs-sync --version 打印当前安装的版本。

配置

默认目录是 ~/.config/cs-sync/。Windows 上是 %USERPROFILE%\.config\cs-sync。环境变量 CS_SYNC_HOME 可以改到别处。

~/.config/cs-sync/
  host.json
  projects/
    我的项目.json

host.json

| 字段 | 含义 | |------|------| | baseUrl | code-server 根地址 | | cookie | code-server-session=… | | auth | 例如 password 或 none | | insecure | 是否跳过 TLS 校验 |

projects/*.json

| 字段 | 含义 | |------|------| | name | 项目简称 | | localRoot / remoteRoot | 本机目录 / 云端绝对路径 | | port | 云端 recv 端口,默认从 27182 递增 | | token | 项目令牌 | | ignoreDirs | 忽略的目录名 |

配置文件按 0600 写入。Windows 上权限由系统落成它能表达的结果。项目名区分大小写。

使用时要注意

  • 外网要先登录 code-server,才能到达同步接口。
  • 持有项目 token 才能对 recv 做写入。/health 不校验令牌。
  • recv 在云端监听 0.0.0.0,经 code-server /proxy 访问。端口不要对公网直接开放。
  • host.json 可能含登录相关字段。它不是系统钥匙串。
  • token 会出现在云端进程的命令行里,同机可以看见。
  • 正式同步前的暂存是 git add -A,会改动对应仓库的 index。--dry-run 不会暂存。
  • 常见初始化路径下,HTTPS 可能跳过证书校验。
  • 单个文件超过约 32MB 时,上传和下载都会拒绝。

常见问题

| 现象 | 可能原因 | 处理 | |------|----------|------| | doctor 返回网页 | Cookie 失效或未登录 | 在本机重新执行 cs-sync login 或 cs-sync cookie | | 502 / 连接被拒绝 | 云端 recv 未启动或端口不对 | 在本机再执行 cs-sync token,把打印出的命令贴到云端终端执行 | | 403 | 本机令牌与云端 --token 不一致 | 在本机执行 cs-sync token,用打印出的命令在云端重启 recv | | 提示接收程序过旧 | 云端的包装版本旧,缺接口 | 在云端升级 code-server-sync 并重启 cs-sync recv | | sync 不传启动前就改过的文件 | 只跟踪启动后的增量 | 在本机改用 to-* 或 diff-*,或先看 sync --dry-run | | 冲突后该文件本轮不动 | 同一处行变更合不上 | 人工对齐后再保存,或在本机改用整份 / 行级命令 | | 行级大量失败 | 补丁合不上或是二进制 | 在本机改用整份同步,或先对齐内容 | | 端口被其他程序占用 | 不是本工具的接收进程 | 在云端按提示检查该端口后手动处理 | | sync 断网后又连上 | 监视循环接住超时和连接失败,进程不退出 | 网络恢复后下一轮自动继续,不必重启这次 sync。| | 大文件没有出现在同步结果里,或提示「文件过大」 | 单个文件超过约 32MB(33554432 字节) | 整份扫描会跳过它,不上传也不下载。sync 打印「未同步 … :文件过大」。行级里已跟踪的这类文件按二进制跳过,未跟踪的新文件不会进入变更。写入 .cs-syncignore,或改成更小的文件 | | 云端和本地根目录名称不同 | 登记时只分别记录两条路径,同步不比较目录名 | 按各自根目录下的相对路径对齐。本机 C:\work\demo、云端 /srv/other 时,src/app.js 仍按 src/app.js 同步。省略 --name 时,项目简称取本地目录名 |