Skip to main content

Issues Encountered

Deployment Delay​

This is what appears locally after running yarn deploy, showing Done in .... But is the deployment really successful?

Afterward, when visiting https://eurekashadow.github.io/ or the domain https://www.eurekashadow.xin/, the following page appears:

This might be because the free CI/CD resources (Runners) used by GitHub Actions are shared globally, and during peak usage periods, there may be queuing issues. By checking the Actions tab in GitHub, you can see the deployment is in a queued state, so just wait patiently. After some time, the deployment will succeed:

After further use, it was discovered that after fixing the CNAME issue, this so-called deployment delay problem no longer occurred. Perhaps it wasn’t due to peak usage periods at all—the real culprit might have been the incorrect CNAME.txt file!

About CNAME​

While reading this article, the author mentioned creating a blank CNAME.txt file in the static directory.

The issue I encountered was that every time the local deployment completed, the custom domain would disappear on GitHub's end, like this: (even though I had already entered the domain earlier)

Problem Analysis

Re-entering the domain:

After entering the domain, GitHub Actions is triggered again:

At this point, when I checked the git-pages branch in the GitHub repository, I noticed it had generated a CNAME file (as shown below, with no file extension), containing my domain www.eurekashadow.xin. I speculate that this CNAME file was automatically generated when re-adding the Custom domain on GitHub. So, was the previously mentioned CNAME.txt unnecessary? Or should the correct approach have been to create a CNAME file and add the domain www.eurekashadow.xin inside it?

Content of the CNAME file:

CNAME Issue Conclusion​

After testing, it was confirmed that CNAME.txt is indeed redundant! The correct approach is:

Create a no-extension CNAME file

Add your domain to the newly created CNAME file:

After this, the deployment should proceed normally:

yarn deploy

The domain names on Github will not be lost.：

Highlighting conflicts with line numbers (not resolved)​

This is my docusaurus.config.js configuration:

docusaurus.config.js
prism: {
  // Code highlighting theme - Light theme uses GitHub style
  theme: prismThemes.github,
  // Code highlighting theme - Dark theme uses the Dracula style
  darkTheme: prismThemes.dracula,
  
  // Custom code highlighting configuration
  magicComments: [
	// Highlighting - Used to emphasize important code lines
	{
	  className: 'code-block-highlighted-line',  // CSS class name
	  line: 'highlight-next-line',               // Inline markup
	  block: { start: 'highlight-start', end: 'highlight-end' }  // Block tag
	},
	// New code marker - Used to identify newly added code lines
	{
	  className: 'code-block-add-line',
	  line: 'highlight-add-line',
	  block: { start: 'highlight-add-start', end: 'highlight-add-end' }
	},
	// Update code markers - Used to identify modified code lines
	{
	  className: 'code-block-update-line',
	  line: 'highlight-update-line',
	  block: { start: 'highlight-update-start', end: 'highlight-update-end' }
	},
	// Error code marker - Used to identify problematic code lines
	{
	  className: 'code-block-error-line',
	  line: 'highlight-error-line',
	  block: { start: 'highlight-error-start', end: 'highlight-error-end' }
	},
  ],
  
  // Additional supported languages (beyond the default list of supported languages)
  // Default supported language list reference:https://github.com/FormidableLabs/prism-react-renderer/blob/master/packages/generate-prism-languages/index.ts#L9-L23
  // Prism.js Complete list of supported languages:https://prismjs.com/#supported-languages
  additionalLanguages: [
	'java',   // Java programming language
	'json',   // JSON data format
	'c',
  ],
},

This is about the configuration of custom.css:

custom.css
/* Style of the code highlighted lines */
.code-block-highlighted-line {
  background-color: rgba(255, 255, 0, 0.2); /* Yellow Highlight */
  display: block;
  margin: 0; /* Avoid layout issues */
  padding: 0 1em; /* Using em units is more flexible */
}

.code-block-add-line {
  background-color: rgba(0, 255, 0, 0.2); /* New Green Feature */
  display: block;
  margin: 0;
  padding: 0 1em;
}

.code-block-update-line {
  background-color: rgba(0, 0, 255, 0.2); /* Blue Update */
  display: block;
  margin: 0;
  padding: 0 1em;
}

.code-block-error-line {
  background-color: rgba(255, 0, 0, 0.2); /* Red Error */
  display: block;
  margin: 0;
  padding: 0 1em;
}

/* Styles for dark theme */
html[data-theme='dark'] .code-block-highlighted-line {
  background-color: rgba(255, 255, 0, 0.2);
}

html[data-theme='dark'] .code-block-add-line {
  background-color: rgba(0, 255, 0, 0.2);
}

html[data-theme='dark'] .code-block-update-line {
  background-color: rgba(0, 0, 255, 0.2);
}

html[data-theme='dark'] .code-block-error-line {
  background-color: rgba(255, 0, 0, 0.2);
}

This is the method of using both highlighting and line numbers:

\```c showLineNumbers
#include <stdio.h>

int main() {
    //Highlight the next line( highlight-next-line)
    printf("Hello, World!\n");
    
    //Highlighting begins( highlight-start)
    int x = 10;
    int y = 20;
    int sum = x + y;
    //Highlighting ends( highlight-end)
    
    return 0;
}
\```

This is an example of a conflict situation:

Highlighting and line numbers can be used separately, but using both together will cause conflicts. Others can all use them normally. Why can't I? The reason has not been identified yet! The temporary compromise solution is to use the two separately. (20250919)

📦 The excessive size of node_modules causes lag issues​

🎯 Problem Phenomenon​

Obvious performance issues were observed in the local development environment:

  • When the size of the node_modules folder becomes excessively large (reaching 17GB), the locally running website experiences severe lag.
  • Navigation between pages is slow, usually taking more than 3 seconds to complete.
  • The compilation time of the development server significantly increases.
  • The overall development experience deteriorates, affecting work efficiency.

🔧 Issue resolved​

Solve this Issue by cleaning the node_modules folder:

bash
npm install rimraf -g                           # Install the rimraf tool
rimraf node_modules                             # Delete "node_modules"
npm cache clean --force                         # clear cache
# npm config set registry https://registry.npmmirror.com/  # Use the new Taobao mirror (optional)
npm install                                     # Reinstall dependencies

✨ The effect after cleaning​

  • The size of node_modules has been reduced from 17GB to approximately 200MB.
  • The compilation speed of the project has significantly improved.
  • Page transitions are completed almost instantly.
  • The local development environment runs smoothly.

💡 Why is cleaning safe?​

  1. Dependency Declaration Mechanism
  • All the actual dependencies used by the project are clearly recorded in the package.json file
  • node_modules is merely the "instantiation" result of these declared dependencies
  • When reinstalling, all the necessary dependencies will be restored according to the package.json file
  1. Design Principles of npm/yarn
  • The package manager ensures that all the dependencies specified in the package.json file are correctly installed.
  • It will not omit any explicitly declared dependencies during reinstallation.

📝 Conclusion of the issue​

The excessive size of node_modules can significantly affect the performance of the local development environment. Regular cleaning is an effective method to maintain the efficient operation of the development environment. This issue is particularly prominent in large projects and should be carried out as a routine maintenance task.

⚠️ Important Update (Further Observation)​

Further practice has revealed that the sluggishness of the development environment may have multiple causes:

  1. node_modules size issue (This section mainly discusses)
  2. Docusaurus build cache issue (This might be more important) If merely cleaning the node_modules directory doesn't yield significant results, it is recommended to try clearing the Docusaurus build cache.

🚀 A truly effective solution​

yarn clear

This indicates that the sluggishness of the development environment is mainly caused by the build cache and the status of the development server, rather than the size of the node_modules. However, it is still necessary to regularly clean up unnecessary dependencies, which can effectively reduce disk space waste.

The Issue of the build folder being too large​

This problem had been lingering for a very long time, but finally it was resolved. I'm very relieved! ~🥱

Problem Description​

The "build" folder, or more precisely, the six js files within it, are extremely large, each being approximately 20mb in size. This ultimately results in the build folder reaching a total size of 128mb. I asked the AI about it and it said this is a very abnormal situation. Even large-scale file servers' build folders usually do not reach this magnitude.

Solution Process​

So I tried every possible way to "slim down" the build process. At first, I discovered that the ForMDX.js file imported large libraries that were not being used. At that moment, I almost thought the problem was solved. But when I checked the build attribute and it was still 128mb, it hit me like a ton of bricks. I was about to break down at that moment. It's already 2 o'clock in the morning. Ugh, haven’t watched Mortal’s Journey today. Curious about Han Li’s demonic psyche in this episode. Then, with the assistance of the AI, I gradually investigated but still couldn't find the problem. Later, an idea struck me, and I deleted the unused src/components/FileBlock.tsx and src/theme/MDXComponents.tsx files. The problem was solved! The build was successful and "thinned out", becoming around 13mb.

Current Status​

At present, there is neither joy nor regret, just a sense of numbness. Let's deal with the further records of this issue tomorrow. For now, I am going to bed.

AI-generated question summary

Problem Background​

  • Observation: The build folder abnormally grew to 128MB in size
  • After resolution: After deleting two incomplete files, the build folder returned to a normal size of 13MB
  • Root cause:
    • Kept src/components/FileBlock.tsx
    • Kept src/theme/MDXComponents.tsx
    • But didn't complete the plugins configuration in docusaurus.config.js

Root Cause Analysis​

Primary Causes​

  1. Circular dependency and improper imports

    • FileBlock component used require('!!raw-loader!@site/' + filepath)
    • Dynamic imports caused webpack to attempt processing all project files

  2. MDX component circular references

    • MDXComponents.tsx re-exported the CodeBlock component
    • Created confusion in component mapping

  3. Build tool misconfiguration

    • Webpack failed to properly resolve dependencies
    • Numerous unnecessary files were bundled
    • Generated incorrect code-split chunks

Problem Resolution Process​

Complete Issue Chain​

Unfinished FileBlock component → Dynamic raw-loader imports → Webpack attempts to process all files → 
Massive duplicate bundling → Incorrect code splitting → Oversized JS file generation → 128MB build output

Solution​

After removing the two problematic files, webpack resumed normal operation:

  1. Eliminated dynamic import source
  2. Restored normal component mapping
  3. Resolved build tool confusion

Lessons Learned​

Key Development Practices​

  1. Hidden Dangers of Unfinished Features

    • Residual code can significantly impact the project even when inactive
    • Regularly clean up unused code files

  2. Risks of Dynamic Imports

    • Exercise caution with dynamic paths like require('!!raw-loader!@site/' + filepath)
    • May trigger build tools to process all potential files

  3. Component Override Considerations

    • Ensure default Docusaurus component overrides don't break existing dependencies

Preventive Measures​

  • Regularly clean up unused code files
  • Use separate branches for experimental features
  • Periodically check dependencies of custom components
  • Pay attention to proper theme component overrides

Follow-up Recommendations​

For reimplementing file import functionality:

  1. Complete full plugin configuration, especially exclude rules
  2. Limit file access scope using allowlist mechanism
  3. Avoid fully dynamic paths - use more specific path patterns

Conclusion​

The 13MB build size is normal, confirming the issue is fully resolved. This case demonstrates that in frontend development, problems may originate from seemingly unrelated residual files, may originate from seemingly unrelated residual files, highlighting the importance of thorough cleanup of unfinished features.

CardImg Component Image Click Freeze Issue​

The original image component code was located in ForMDX.js, and was later migrated out to CardImg.js.

In CardImg.js, the following should be imported:

import { PhotoProvider, PhotoView } from 'react-photo-view';
import Lazyimg from 'react-lazyimg-component';
import 'react-photo-view/dist/react-photo-view.css';

In fact, it is lacking:

import 'react-photo-view/dist/react-photo-view.css';

Since ForMDX.js still kept those three imports, CardImg.js had an implicit dependency on ForMDX.js, making the image component work properly at that time.

Later while troubleshooting the oversized build folder issue, those three imports in ForMDX.js were found to be redundant and got removed. This broke the implicit dependency, causing the image component to stop working.

These implicit dependency issues can be nasty to debug. In this case, the image component could at least be refactored to restore functionality. But if faced with a situation where refactoring becomes extremely difficult or nearly impossible, tracking down such implicit dependencies would be a nightmare!

Got lucky this time - vaguely remembered the image component needed those three imports, so the fix was straightforward. Let this serve as a reminder: avoid creating such hidden dependencies in the first place. 🥱

Resolving Vercel Preview Deployment Errors​

Problem Description​

When deploying to the gh-pages branch of GitHub Pages using yarn deploy, Vercel automatically detects branch changes and attempts to create a Preview deployment. However, since the gh-pages branch only contains static files without a package.json, the build fails, showing a ❌preview error in GitHub Deployments.

Root Cause​

  • Vercel by default creates Preview deployments for all branch pushes
  • The gh-pages branch contains only built static files, lacking source code and build configuration
  • Vercel fails when attempting to run npm run build

Solution​

Configure Production Build:

  1. Go to Vercel project Settings → Git
  2. Under Behavior options, select "Only build production"
  3. Ensure the production branch is set to main (or your primary branch)
  4. Save settings
加载评论中...