mirror of https://github.com/CherryHQ/cherry-studio.git synced 2026-07-03 12:27:41 +08:00

Files

亢奋猫 12735d3b12 feat(preboot): support multi-instance dev userData suffix (#15731 )

> ### 🚨 Branch strategy — read before opening this PR
>
> The v2 refactor has merged into `main`, so **`main` is the default
branch for active development** (v1 and v2 code currently coexist there
— expect large, breaking changes).
>
> - **Active development** (features, refactors, optimizations, fixes
for the current codebase) → target **`main`** (the default base).
> - **v1 maintenance** (hotfixes and subsequent v1 releases) → branch
from and target **`v1`**, _not_ `main`.
>
> A v1 fix does **not** auto-carry to `main`: if the same bug exists on
`main`, open a separate forward-port PR targeting `main`. Before
touching subsystems being replaced, read `docs/references/data/` and
watch for `@deprecated` markers — they flag code being deleted.

### What this PR does

Before this PR:

Development builds always used the fixed `Dev` suffix for Electron's
default `userData` path, so parallel dev instances shared the same app
data path and single-instance lock.

After this PR:

Development builds can set `CS_DEV_USER_DATA_SUFFIX` to use a unique
`userData` suffix per dev instance. Blank values fall back to `Dev`. The
development guide, preboot reference, and `.env.example` document both
`.env` and inline command usage. `pnpm debug` also loads `.env` through
`dotenv`, matching `pnpm dev` while preserving Electron argument
passthrough with `dotenv -- electron-vite -- ...`.

<!-- (optional, in `fixes #<issue number>(, fixes #<issue_number>, ...)`
format, will close the issue(s) when PR gets merged)*: -->

Fixes # N/A

### Why we need it and why it was done in this way

The following tradeoffs were made:

This keeps the change scoped to the existing preboot dev `userData`
suffix path instead of introducing a new config system. The suffix is
trimmed and empty values fall back to the current default to avoid
accidentally running dev against the unsuffixed packaged data path.

The following alternatives were considered:

Adding a dedicated package script for each development instance was not
chosen because instance names are local developer concerns. A single
environment variable is enough and works from either `.env` or one-off
shell commands.

Links to places where the discussion took place: N/A

### Breaking changes

N/A

### Special notes for your reviewer

This is dev-only behavior. Packaged builds still use the existing
BootConfig-driven userData resolution path.

### Checklist

This checklist is not enforcing, but it's a reminder of items that could
be relevant to every PR.
Approvers are expected to review this list.

- [x] Branch: This PR targets the correct branch — `main` for active
development, `v1` for v1 maintenance fixes
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: [Write code that humans can
understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans)
and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle)
- [ ] Refactor: You have [left the code cleaner than you found it (Boy
Scout
Rule)](https://learning.oreilly.com/library/view/97-things-every/9780596809515/ch08.html)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [ ] Documentation: A [user-guide update](https://docs.cherry-ai.com)
was considered and is present (link) or not required. Check this only
when the PR introduces or changes a user-facing feature or behavior.
- [x] Self-review: I have reviewed my own code (e.g., via
[`/gh-pr-review`](/.claude/skills/gh-pr-review/SKILL.md), `gh pr diff`,
or GitHub UI) before requesting review from others

### Release note

<!--  Write your release note:
1. Enter your extended release note in the below block. If the PR
requires additional action from users switching to the new release,
include the string "action required".
2. If no release note is required, just write "NONE".
3. Only include user-facing changes (new features, bug fixes visible to
users, UI changes, behavior changes). For CI, maintenance, internal
refactoring, build tooling, or other non-user-facing work, write "NONE".
-->

```release-note
NONE
```

---------

Signed-off-by: kangfenmao <kangfenmao@qq.com>
Co-authored-by: fullex <106392080+0xfullex@users.noreply.github.com>

2026-06-16 18:51:30 +08:00

2.3 KiB

Raw Permalink Blame History

🖥️ Develop

IDE Setup

VSCode like

Editor: Cursor, etc. Any VS Code compatible editor.
Recommended extensions are listed in .vscode/extensions.json.

Zed

Install extensions: Biome, oxc
Copy the example settings file to your local Zed config:
```
cp .zed/settings.json.example .zed/settings.json
```
Customize .zed/settings.json as needed (it is git-ignored).

Windows: Enable Symlinks

This project uses symlinks to synchronize files such as AGENTS.md and skills. Windows developers must enable symlink support before cloning:

Enable Developer Mode (Settings → Update & Security → For developers), or grant SeCreateSymbolicLinkPrivilege via secpol.msc.
Configure Git:
```
git config --global core.symlinks true
```
Clone (or re-clone) the repository after enabling symlink support.

Project Setup

Install

pnpm install

Development

Setup Node.js

The required Node.js version is defined in .node-version. Use a version manager like nvm or fnm to install it automatically:

nvm install

Setup pnpm

The pnpm version is locked in the packageManager field of package.json. Just enable corepack and it will use the correct version automatically:

corepack enable

Install Dependencies

pnpm install

ENV

cp .env.example .env

Start

pnpm dev

By default, development runs append Dev to Electron's default userData directory, keeping local dev data separate from packaged app data. To run multiple development instances at the same time, give each instance a unique suffix. You can set it in .env:

CS_DEV_USER_DATA_SUFFIX=DevQuito

Or pass it inline when starting a dev instance:

CS_DEV_USER_DATA_SUFFIX=DevQuito pnpm dev
CS_DEV_USER_DATA_SUFFIX=DevParis pnpm dev

Blank values are ignored and fall back to Dev.

Debug

pnpm debug

Then input chrome://inspect in browser

Test

pnpm test

Build

# For windows
$ pnpm build:win

# For macOS
$ pnpm build:mac

# For Linux
$ pnpm build:linux

2.3 KiB Raw Permalink Blame History