企业官网建设流程全解析

lightweight-charts 调试沙箱完全指南：基于 debug 目录搭建本地开发与试验环境

【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts

本文围绕 debug/README.md 展开，系统讲解 lightweight-charts 仓库中debug目录的定位、设计原理与完整使用流程——从初始化公共根目录、创建独立沙箱、构建本地源码、启动开发服务器（含生产构建模式）到清理沙箱的每一步。读完本文，你将掌握一套"不污染主代码库"的轻量级试验环境搭建方法，可随时用本地构建的 lightweight-charts 源码验证自定义图表、系列（Series）与插件（Plugin）效果，并理解其基于 npm workspaces 的多沙箱共享依赖机制。

debug 目录的定位与设计初衷

在 lightweight-charts 仓库（当前版本 5.2.1，见 package.json）中，debug目录承担着一个特殊的职责：为贡献者提供一个不会被提交到版本库的调试与试验沙箱环境。

从 debug/README.md 的说明可以提炼出它的三个核心设计目标：

1. 安全隔离：所有调试文件创建在playground/目录下，且 debug/.gitignore 中只有一行*，意味着debug目录下的任何新建文件都不会进入 Git 版本库，不影响主代码库。
2. 快速上手：内置一份default默认模板（包含 index.html、index.ts、tsconfig.json），执行一条命令即可生成可运行的示例页面。
3. 多沙箱管理：提供 create / serve / remove 一套脚本，方便同时维护多个相互独立的试验沙箱，并让所有沙箱共享同一份依赖。

在官方构建文档 BUILDING.md 中也有明确指引：想"使用本地构建的包进行试验"时，请遵循 debug/README.md 创建沙箱进行开发。这说明该目录是官方认可的本地开发调试入口。

核心机制：两个 JSON 模板 + npm workspaces

要理解整个沙箱体系，需要先看清debug目录下的关键配置文件，因为它们定义了沙箱的"骨架"。

入口脚本清单（debug/package.json）

debug/package.json 是所有命令的中转站，它把具体工作转发给playground目录：

{ "name": "playground_root", "os": ["darwin", "linux"], "private": true, "scripts": { "init": "mkdir playground && cp default/.global.json playground/package.json && cp .npmrc playground && npm install --prefix playground;", "create": "npm run --prefix playground create", "remove": "npm run --prefix playground remove", "list": "npm run --prefix playground list", "serve": "npm run --prefix playground serve", "serve:prod": "NODE_ENV=production npm run --prefix playground serve" } }

两点值得注意的源码事实：

• "os": ["darwin", "linux"]声明该工具链面向 macOS 与 Linux，内部脚本大量使用sh -c，因此在 POSIX shell 环境（macOS / Linux 终端）下工作最顺畅。
• serve:prod通过设置环境变量NODE_ENV=production来切换运行模式，其背后机制详见下文"运行沙箱"一节。

全局模板：default/.global.json

init命令会把 debug/default/.global.json 复制为playground/package.json，成为所有沙箱的公共根配置：

{ "dependencies": { "lightweight-charts": "file://../.." }, "devDependencies": { "typescript": "5.5.4", "vite": "7.2.0" }, "private": true, "workspaces": ["./*"], "scripts": { "create": "sh -c 'mkdir -p $1.d && cd $1.d && cp ../../default/.local.json package.json && cp ../../default/* . && npm install' -", "remove": "sh -c 'rm -fr $PWD/${1##*/}.d' -", "serve": "sh -c 'vite $1.d' -" } }

从这个模板可以看出沙箱体系的两大设计支柱：

• 本地依赖：lightweight-charts通过file://../..指向仓库根目录。由于根目录 package.json 的main/module/exports都指向dist/下的构建产物（如dist/lightweight-charts.production.mjs），所以必须先构建仓库源码，沙箱才能解析到本地版本——这正是 README 强调"Ensure that lightweight-charts is built"的原因。
• 依赖共享：workspaces: ["./*"]把playground下的每个沙箱目录（<NAME>.d）注册为工作区。当你在某个沙箱里npm install额外包时，npm 会把公共依赖提升到playground/node_modules，于是所有沙箱（包括未来新建的）共享同一份依赖，避免重复安装。

本地模板：default/.local.json

每个沙箱创建时，其自身package.json来自 debug/default/.local.json，内容为空对象{}。沙箱本身不做版本声明，所有依赖解析统一交给上层的 workspaces 根处理。

环境配置文件

• debug/.npmrc：package-lock = false（不生成 lock 文件）、fund = false、audit = false、loglevel = error，让安装过程更安静、更轻量，符合调试场景。
• debug/.gitignore：内容为*，配合前文所述，保证playground与沙箱文件永不入库。

第一步：初始化公共根目录

首次使用前，需要在debug目录下执行：

npm run init

这条命令实际执行（见 debug/package.json）：

mkdir playground && cp default/.global.json playground/package.json && cp .npmrc playground && npm install --prefix playground;

即依次完成：

1. 创建playground/目录（所有沙箱的父目录）；
2. 将全局模板.global.json复制为playground/package.json；
3. 复制.npmrc到playground；
4. 在playground下执行npm install，安装 lightweight-charts（本地路径）、typescript、vite 等公共依赖。

初始化成功后，debug/playground/即为沙箱体系的工作根。

第二步：构建本地 lightweight-charts

由于沙箱依赖本地源码副本（file://../..），在创建/运行沙箱之前必须先构建仓库根目录的产物：

npm run build --prefix ..

--prefix ..表示在debug的上层目录（即仓库根目录）执行。根目录的build脚本为npm-run-all tsc rollup bundle-dts（见 package.json），会依次完成 TypeScript 编译（tsc）、Rollup 打包（rollup）和声明文件打包（bundle-dts），最终生成dist/下的各类构建产物（development、production、standalone 等）。

第三步：创建沙箱

在debug目录下执行：

npm run create <NAME>

将<NAME>替换为沙箱名称，即可在playground/<NAME>.d下创建沙箱。该命令经npm run --prefix playground create转发到全局模板中定义的：

sh -c 'mkdir -p $1.d && cd $1.d && cp ../../default/.local.json package.json && cp ../../default/* . && npm install' - <NAME>

具体动作：

1. 创建目录playground/<NAME>.d；
2. 将default/.local.json复制为该沙箱的package.json；
3. 将default模板下的所有文件复制进沙箱（index.html、index.ts、tsconfig.json、.local.json等）；
4. 执行npm install——由于处于 workspaces 体系中，依赖会安装/复用共享的playground/node_modules。

默认模板内容剖析

新建沙箱默认自带一个可直接运行的示例页面，三份文件各司其职：

debug/default/index.html提供容器节点与入口加载：

<html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> </head> <body style="padding: 0; margin: 0"> <div id="container" style="position: absolute; width: 100%; height: 100%"></div> <script type="module" src="index.ts"></script> </body> </html>

debug/default/index.ts演示了 lightweight-charts v5 的典型用法：createChart创建图表、chart.addSeries(AreaSeries, ...)添加面积系列、chart.addSeries(CandlestickSeries, ...)添加蜡烛系列，最后chart.timeScale().fitContent()自适应缩放：

import { AreaSeries, CandlestickSeries, ChartOptions, createChart, DeepPartial, } from "lightweight-charts"; const chartOptions = { autoSize: true, } satisfies DeepPartial<ChartOptions>; const chart = createChart('container', chartOptions); const areaSeries = chart.addSeries(AreaSeries, { lineColor: "#2962FF", topColor: "#2962FF", bottomColor: "rgba(41, 98, 255, 0.28)", }); areaSeries.setData([ { time: "2018-12-22", value: 32.51 }, { time: "2018-12-23", value: 31.11 }, // ... 更多数据点见 debug/default/index.ts ]); const candlestickSeries = chart.addSeries(CandlestickSeries, { upColor: "#26a69a", downColor: "#ef5350", borderVisible: false, wickUpColor: "#26a69a", wickDownColor: "#ef5350", }); candlestickSeries.setData([ { time: "2018-12-22", open: 75.16, high: 82.84, low: 36.16, close: 45.72 }, // ... 更多数据点见 debug/default/index.ts ]); chart.timeScale().fitContent();

debug/default/tsconfig.json采用ESNext目标与strict严格模式，启用noUnusedLocals、noUnusedParameters、noImplicitReturns等编译检查，并开启emitDeclarationOnly生成声明文件——与仓库主代码的编码规范保持一致，保证沙箱代码质量。

第四步：运行沙箱

开发模式（实时刷新）

在debug目录下执行：

npm run serve <NAME>

该命令最终执行vite <NAME>.d（见全局模板中的serve脚本），由 Vite 启动一个 Web 服务器：

• 编译 TypeScript（内置支持）；
• 提供playground/<NAME>.d目录下的静态资源；
• 文件变更时自动热更新（live reload），保存代码后浏览器即时刷新，非常适合边改边调试图表效果。

生产构建模式

如需验证生产（压缩）构建下的表现，执行：

npm run serve:prod <NAME>

它等价于NODE_ENV=production npm run --prefix playground serve。关键原理在根目录 package.json 的exports字段：

".": { "development": { "types": "./dist/typings.d.ts", "import": "./dist/lightweight-charts.development.mjs" }, "production": { "types": "./dist/typings.d.ts", "import": "./dist/lightweight-charts.production.mjs" }, "default": { "types": "./dist/typings.d.ts", "import": "./dist/lightweight-charts.production.mjs" } }

Vite 会根据NODE_ENV自动选择对应的导出条件：开发模式加载lightweight-charts.development.mjs（含调试信息），生产模式加载lightweight-charts.production.mjs（压缩产物）。两种模式下的类型声明均来自dist/typings.d.ts，保证了类型体验一致。

第五步：删除沙箱

不再需要某个沙箱时，在debug目录下执行：

npm run remove <NAME>

该命令执行rm -fr $PWD/<NAME>.d（经全局模板中的remove脚本），递归删除playground/<NAME>.d下的全部内容及目录本身。需要注意：这只移除沙箱自身，公共的playground/node_modules共享依赖不受影响，其他沙箱仍可正常使用。

管理多个沙箱与扩展依赖

• 多沙箱并存：每次npm run create <NAME>都会生成独立的<NAME>.d目录，各沙箱拥有自己的index.ts/index.html，互不干扰，可并行调试不同的图表方案。
• 扩展依赖：在任何沙箱内npm install <pkg>安装的包，因 workspaces 机制会被提升到共享的playground/node_modules，对所有现有及未来沙箱立即可用——这是 README 中"any installed package will be shared across all sandboxes"的底层实现。
• 关于 list 命令：debug/package.json 中还声明了list脚本（转发npm run --prefix playground list），但从源码结构看，默认模板 .global.json 中并未定义对应的list脚本，如需使用请以实际 playground 配置为准。

从零到一的完整流程速查

总结

debug目录为 lightweight-charts 贡献者提供了一套"零侵入、多实例、依赖共享"的本地调试方案：通过default双 JSON 模板（.global.json定义共享根、.local.json定义沙箱本体）与 npm workspaces 机制，实现了所有沙箱共用同一份本地构建与第三方依赖；NODE_ENV=production与根目录exports条件导出配合，还能无缝切换开发/生产构建进行验证。整个工作流与 BUILDING.md 中"使用本地构建包进行开发"的指引一脉相承，是深入理解 lightweight-charts 源码、试验自定义系列与插件的首选入口。相关核心文件均可直接阅读源码进一步研究：debug/package.json、debug/default/.global.json、debug/default/index.ts、debug/default/index.html 与 debug/default/tsconfig.json。

【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts