Astryx 中文教程：React 19 安装、主题接入与 CLI 使用

Astryx 不是单独的一组无样式组件。它把 150 多个 React 组件、CSS 变量主题、页面模式、模板和 CLI 放在同一套约定里。官方称这套系统在 Meta 内部演进多年，开源版本目前仍标为 Beta。

1. 安装前先检查 React

官方 core README 要求 react 和 react-dom 至少为 19.0.0。老项目如果还在 React 18，先评估升级和现有组件库的兼容性。

npm ls react react-dom
npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
npm install -D @astryxdesign/cli

普通使用不需要给项目增加 StyleX、PostCSS 或 Babel 构建插件。Astryx 已经发布预构建 CSS 和 JavaScript；@stylexjs/stylex 仍是官方安装命令列出的运行依赖。

2. CSS 顺序不能随便换

把下面三行放入应用的全局 CSS。顺序对应 reset、组件基础样式和主题覆盖层：

@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-neutral/theme.css';

然后按照 官方 core README 为框架配置 Theme。Next.js 还需要按示例接入 LinkProvider，不要把别的框架示例原样复制过去。

3. 先用 CLI 查组件，再写代码

npx @astryxdesign/cli component --list
npx @astryxdesign/cli docs theme
npx @astryxdesign/cli swizzle Button

component 和 docs 适合开发者或 Agent 查询当前包的用法。swizzle 会把组件源码复制进项目，之后升级不会自动替你合并这份本地代码，使用前要明确维护责任。

4. 和 Radix Primitives 怎么选

相比 Radix Primitives，Astryx 更接近可直接交付界面的完整设计系统：它有预构建视觉样式、多个主题、模板和 CLI。Radix 官方强调无视觉样式、可组合的交互原语，视觉系统主要由使用方完成。需要统一成品界面时先试 Astryx；需要完全自定义视觉且只要交互基础时，Radix 的边界更清楚。

5. 验证边界

真正接入时至少检查：React 版本、三层 CSS 的加载顺序、明暗主题切换、键盘操作和构建产物。下一次更新本文时，应重新核对 Latest release、core README 的 peer dependencies，以及 charts 是否已经从 canary 转为稳定版。

常见问题